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Preface 


This manual describes the VAX FMS Form Driver, the run-time component 
of the Forms Management System for use with the VAX/VMS operating 


system. 


Intended Audience 


The manual is intended for programmers who wish to use FMS with any of 
their application programs being written in BASIC, BLISS—32, C, COBOL, 
FORTRAN, PASCAL, or PL/I (those languages documented in the VAX FMS 
Lar.guage Interface Manual). Readers are expected to be familiar not only 
with a programming language but with the VAX/VMS system. 


Readers are also expected to be familiar with the information in Chapter 2 of 
the VAX FMS Utilities Reference Manual, Form Characteristics. This mate- 
rial discusses form characteristics that are specified by means of the Form 
Editor or Form Language when a form is being designed. 


Readers having little or no experience with FMS are urged to read the Intro- 
duction to VAX FMS before reading this manual. 
Chapter Summary 


Chapter 1 presents an overview of the Form Driver, briefly discussing 12 
basic topics. 


_ Chapter 2 discusses Form Driver interaction with form descriptions, user 


action routines, terminal operators, key functions and key codes, call status, 
and asynchronous system traps (ASTs). 


Chapter 3 offers programming techniques and examples from the Sample 
Application Program in various languages. The FMS Sample Application 
program (SAMP.BAS), a part of the FMS distribution kit, is designed to be a 
demonstration program and learning tool. (Examples from SAMP appear 
throughout the FMS document set.) 


Chapter 4 shows how to link object modules with the Form Driver and, 
optionally, with memory-resident forms or user action routines. This chapter 
also discusses terminal use in FMS programs. 


ix 


Chapter 5 describes all Form Driver calls in alphabetical order, each giving 
first the generic format of the call with its arguments, followed by definitions 
of all arguments in the order they must be specified (along with information 
on how they are passed and whether they are read or written), then a descrip- 
tion of what the call does, and finally a list of status codes (in alphabetical 
order) that can be returned to the program as a result of the execution of the 
call. : 


Throughout this manual, names of calls are usually referred to informally as, 
for example, CDISP. When calls are actually issued in programs, though, all 
names of FMS calls begin with the prefix FDV$ (for example, FDV$CDISP). 
To find the language-specific way of issuing a call, you must consult the 
appropriate chapter in the VAX FMS Language Interface Manual. 


In this manual the phrase “GET-type calls” refers to any of the following 

calls: GET, GETAF, GETAL, and GETSC (but not GETDL). The phrase 

_ “PUT-type calls” refers to the calls PUT, PUTAL, PUTD, PUTDA, and 
PUTSC (but not PUTL). 


Appendix A gives a comprehensive summary of information on all FMS calls. 


Documentation Conventions 
Uppercase letters In commands and examples, indicate that the user 
types the item exactly as shown. 


Lowercase letters In commands and examples, indicate variables for 
which the user is to substitute a word or value. 


Brackets [ ] Indicate that the item is optional. 

Braces { } Enclose lists from which one element is to be chosen. A 
vertical bar (|) separates the choices. 

Red print Indicates what the user types. 

CTRL/x Indicates that the user holds down the key labeled 
CTRL and presses another key. 

Gold x Indicates that the user presses the Gold key before 
pressing the second key. 


Ellipsis... Indicates that the preceding item can be repeated. 


Chapter 1 
Introduction 


The Form Driver, the run- | time component of FMS, is a subroutine package 
that is linked with your program. The Form Driver accepts calls from your 
program, maintains FMS data structures, and issues terminal I/O calls to 
communicate with the terminal operator. 


As shown in Figure 1—1, the Form Driver is one of three parts of an FMS 


application. 
Application Video i 
Program Terminals 
ZK-1836-84 


Figure 1-1 Form Driver Communication 





Knowledge of the following 12 topics is basic to an understanding of the Form 
Driver. This chapter offers brief introductions to these topics: 


e Terminals, Workspaces, Forms, and Fields 

e Terminal Control Areas and Form Workspaces 
e Form Management Calls 

¢ Memory-Resident Forms and Form Libraries 
e Multiterminal and Multiform Operations 

e Debug Mode 

e Scrolling Operations 

e User Action Routines 

e Named Data 

e Terminal Key Functions 

e Current States 


e Operator Aids 
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1.1. Terminals, Workspaces, Forms, and Fields 


12 


The primary work of the Form Driver is the manipulation of terminal 
images, form workspaces, forms, and form fields. 


1.1.1. Terminals 


The Form Driver controls one or more terminals, performing such tasks as 
displaying forms, soliciting data from the terminal operator, and displaying 
messages. The terminal is controlled by the character sequences and escape 
sequences sent to it by the Form Driver. 


An application program using FMS can process forms on any of the 
VT100/VT200 compatible terminals or on the VT52 terminal. The Form 
Driver supports calls that manage terminals’ initialization, their use, and 
their release by FMS. 


In an FMS application, a separate area of memory is associated with each 
terminal. This area is called a terminal control area or TCA. Once a TCA is 
associated with a terminal, the application program controls that terminal’s 
activity by issuing calls that specify the terminal’s TCA. 


1.1.2 Workspaces 


Workspaces are areas of memory in which the Form Driver stores form 
descriptions for the forms being processed. More than one form workspace 
can be associated with a terminal, but each workspace can be associated with 
only one terminal at a time. The Form Driver supports calls that initialize 
workspaces, associate them with TCAs, load them with form descriptions, 
and release them from TCAs. 


1.1.3 Forms 


A form consists of (1) background text and fields, which are displayed on the 
screen, and (2) Named Data, which is not displayed. Internally, a form is com- 
posed of the data structures used by the Form Driver to create and manipu- 
late the image on the screen. These data structures (called form descriptions) « 
are created by FMS utilities (Form Editor, Form Language Translator, and 
Form Upgrade Utility). (See the VAX FMS Utilities Reference Manual.) 


The Form Driver supports calls that load these form descriptions into work- 
spaces and perform the many functions defined for forms and their fields. 
When a form is loaded into a workspace, the workspace becomes associated 
with the form. Consequently, reference to a workspace is a reference to the 
form stored in it. 


Because a workspace can be associated with only one terminal at a time, dis- 
playing any given form on more than one terminal requires loading the form 
into workspaces associated with other terminals as well. 
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1.1.4 Fields 


A field is a portion of the form that has variable data associated with it. The 
Form Driver supports many calls controlling the manipulation of field data. 
Some calls allow the terminal operator to enter or change field data. Others, 
for example, allow the application program to display data in fields, to get 
data that the operator entered in fields, or to change field video attributes. 


Field attributes, assigned when a form is created, affect the way the Form 
Driver processes field input and output. For example, a field having the 
Response Required attribute requires that the terminal operator enter at 
least one character in the field. 


When the Form Driver processes groups of fields (in a single form) with a sin- 
gle call, it processes them in the order specified in the form description. The 
Form Driver controls movement from field to field, the order in which field 
values are returned to your program or written to a terminal, and the defini- 
tion of “first” and “last” fields in forms. 


1.2 Terminal Control Areas and Form Workspaces 


Terminal control areas (TCAs) and form workspaces are maintained in a 
hierarchy as shown in Figure 1—2. The application program shown uses sev- 
eral terminals. Attached to the application program is a list of TCAs that tells 
the Form Driver which terminals it can use. Attached to the first TCA is a list 
of workspaces that can contain forms for processing on that TCA’s terminal. 
Similarly, a list of workspaces is attached to the second TCA. 


Application Terminal 
Program Control Areas Workspaces 


Form Driver 
Calls 
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Figure 1-2 Terminal Control Areas and Workspaces 
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Although you refer to forms and fields by name, you usually do not need to 
refer toa TCA name to specify a particular terminal or to refer to a workspace 
name to specify where you want to load a form. The Form Driver establishes a 
“current terminal” and “current workspace”. Each call that affects a terminal 
or workspace acts upon the current terminal or current workspace, unless the 
call explicitly specifies another TCA or workspace. 


The Form Driver provides calls to make another terminal or another work- 
space the current one. By including such calls in your program, you can avoid 
having to specify the terminal and workspace for each call your program 
issues. 


1.3. Form Management Calls 
The Form Driver supports four classes of form management calls: 
1. Control 
2. Form-level 
3. Field-level 
4. Utility 
These calls are introduced in the following sections and documented fully in 
Chapter 5. 
1.3.1 Control Calls 


Your program issues the following calls to make connections and disconnec- 
tions between FMS units such as terminals, form workspaces, files, and form 


libraries: 

ATERM Attach terminal 
AWKSP Attach form workspace 
DTERM Detach terminal 
DWKSP Detach form workspace 
LCHAN Set channel for form library file 
LCLOS Close form library 
LOPEN Open form library 
STERM Set current terminal 
SWKSP Set current workspace 
TCHAN Set terminal channel 
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1.3.2 Form-Level Calls 


Your program issues the following calls to perform general form-level 
operations: 


CDISP Clear screen and display form 

DEL Delete form from memory 

DISP Display form 

DISPW Display loaded form 

GETAL Get all field values 

LOAD Load form without display 

NDISP Mark form in current workspace as not displayed 
PUTAL Output values to all fields in a form 
PUTDA Output default values to all fields in a form 
READ | Read form into memory 

RETAL Return values for all fields in a form 


1.3.3 Field-Level Calls 


Your program issues the following calls to perform field-level operations on a 
form: 


AFCX Alter field context 

AFVA Alter field video attributes 

GET Get value for specified field 

GETAF Get value for any field - 

GETSC Get current line of scrolled area 
PFT Process field terminator 

PUT Output value to specified field 
PUTD Output default to specified field 
PUTSC Output data to current line of scrolled area 
RET Return value for specified field 
RETFN Return current field name 

RETFO Return field names in order 

RETLE Return length of specified field 
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1.3.4 Utility Calls 


Your program issues the following calls to perform operations not falling into 
the preceding classifications: 


ADLVA 
BELL 
CANCL 
CLEAR 
CLEAR_VA 
DFKBD 
DPCOM 
FIX_SCREEN 
GETDL 
ILTRM 
LEDOF 
LEDON 
PUTL 
RETCX 
RETDI 
-RETDN 
RETFL 
RFRSH ~ 
SCR_WIDTH 
SIGOP 
SPADA 
SPOFF 
SPON 
SSIGQ 
SSRV 
STAT 
STIME 
USER_REFRESH 
WAIT 
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Alter data line video attributes 
Ring terminal bell 

Cancel call 

Clear screen 

Clear screen video attributes 
Define keyboard 

Define comma as decimal point 
Repair overwritten lines of terminal screen 
Get data line from terminal 
Return illegal terminators 

Turn terminal LED off 

Turn terminal LED on 

Output line to screen 

Return current context 

Return Named Data by index 
Return Named Data by name 
Return form line 

Refresh screen 

Set screen width 

Signal operator 

Set keypad to application mode 
Turn supervisor-only mode off 
Turn supervisor-only mode on 

Set signal to quiet mode | 

Specify status recording variables 
Return status from last call 

Set field entry timeout 

Set up user-supplied refresh routine 


Wait for operator 
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Memory-Resident Forms and Form Libraries 


The Form Driver gets the forms required by various calls either from a mem- 
ory-resident set of form descriptions or from a form library you specify in a 
Form Driver call. You can make forms memory resident either by building 
them into your application program or by loading them into the set of mem- 
ory-resident forms at run time. Memory-resident form modules are created 
by one of the Form Application Aids; form libraries are built and maintained 
by the Form Librarian. 


Multiterminal and Multiform Operations 


An application program using the Form Driver can control one or more termi- 
nals and manipulate one or more forms on each terminal by using control 
calls (STERM or SWKSP) to define a new current terminal or current work- 
space. Note that for this version of FMS you can use these calls to control only 
one terminal at a time. 


Debug Mode 


The Form Driver has a Debug mode of operation that is useful for the debug- 
ging of an application program that uses FMS. When the application pro- 
gram is in FMS Debug mode, it runs normally until the Form Driver returns 
a status code indicating an error. At this time, a message is displayed on the 
bottom line of the screen, and the Form Driver waits for the operator to press 
the Enter Form key before proceeding. (Any other input is ignored.) 


The Form Driver Debug mode is not associated with any other debugging aid. 


Scrolling Operations 


You can use the GET, GETAF, GETSC, PFT, PUT, and PUTSC calls in your 
program to take advantage of the scrolling capabilities of the VT100. With 
these calls you can control scrolled areas in forms. | 


The hardware scrolling capabilities of the VT100/VT200 are simulated for 
VT52 terminals by software. The performance of scrolling operations is 
therefore much slower for VT52s. 


User Action Routines 


When a form is designed, the form designer can specify that subroutines sup- 
plied by you be called from the Form Driver as part of the processing of the 
form. These subroutines are called user action routines (UARs). 


A user action routine can be called under any of the following conditions: 
1. When processing for a field is finished 

2. When the terminal operator requests help 

3. When the terminal operator presses a function key 


4, When ascreen refresh operation is requested 
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When linking your program, you must include an object module containing 
the names of all the user action routines to be called. You generate such an 
object module by using the FMS/VECTOR command. (See Chapter 4 of this 
manual and the VAX FMS Utilities Reference Manual, Chapter 6, Form 
Application Aids.) 


1.9 Named Data 


Named Data is data first associated with a form when the form is being 
designed. It is not a visible part of the form that appears on the operator’s 
screen. Rather, it is form-oriented information your program can use that you 
might otherwise have to keep in your program. Two calls are available to you 
for accessing this information. (See Chapter 3 for examples of the use of 
Named Data.) 


1.10 Terminal Key Functions 


Many Form Driver actions are taken in response to the pressing of certain 
terminal keys by an operator. FMS has assigned functions to keys, but you 
can change the correspondence between keys and functions to whatever you 
want. Therefore, this manual refers not to a physical key but to the function 
that the key performs (regardless of which key implements the function). 
Accordingly, the name of a key function has its initial letter capitalized 
rather than its entire name capitalized, which is the way names of actual 
keys are indicated. (See Section 2.3 subsections for default definitions of all 
keys used by the Form Driver.) 


1.11 Current States 


1-8 


The Form Driver establishes certain “current states” that are important to 
know about when you are writing your program: 


1. Current Terminal — The terminal (with all its characteristics) currently 
in use 


Although you can control more than one terminal in your FMS applica- 
tion, the Form Driver calls affect only one terminal at a time — the current 
terminal. The Form Driver provides calls to change the current terminal. 


The current terminal is undefined if no terminal is in use. 
2. Current Workspace — The form workspace currently in use 


Although you can work on more than one workspace in your FMS applica- 
tion, the Form Driver calls affect only one workspace at a time — the cur- 
rent workspace. Your program issues calls to change the current 
workspace. The current workspace is associated with the current termi- 
nal. Whenever your program switches to another terminal, therefore, it 
inherits the new terminal’s current workspace. 


The current workspace is undefined if the current terminal is undefined, 
or if no workspace is presently associated with the current terminal. 
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You can manipulate a form only by first loading it into a workspace by 
means of a LOAD, DISP, or CDISP call. 


. Current Field — The most recent field specified in a call for operator input 
(or the first modifiable field in a form, if no input call has been executed 
yet) and any index associated with the field 


The current field normally is available by default when you do not supply a 
name for the field name argument in a subsequent call. 


The current field and its index are associated with the current workspace. 
If your program switches to another workspace, it inherits a new current 
field and index. | 


If a field does not have the Indexed attribute, its index is defined as zero. 


The current field and its index are undefined if there are no fields in the 
form or if no workspace is defined. 


. Current Scrolled Line — The line in any scrolled area that the Form Driver 
is currently working on 


This line is initially the first (top) line in a scrolled area, but you can move 
up or down in the area to a new current scrolled line by issuing a PFT call 
in your program. 


The current scrolled line is aesociated with any scrolled area being worked 
on in the current workspace. The current scrolled line is undefined if the 
form in the workspace has no scrolled areas. 


. Last Terminator Code — The most recent field terminator code returned by 
a call in your program 


This code is associated with the current workspace. If your program 
switches to another workspace, it inherits the new workspace’s last termi- 
nator code. 


The last terminator code is undefined if no field terminator has been 
entered for the form. 


. Last Status Code — The most recent status code returned by a Form Driver 
call in your program 


This code is associated with the current workspace if one is defined. If no 
current workspace is defined, the code is associated with the current ter- 
minal provided one is defined. If no current terminal is defined, the code is 
associated with the Form Driver itself. 


This method of associating the last status code with more than one possi- 
ble object is available so that when your program switches from one termi- 
nal to another, or from one workspace to another, it gets the most recent 
status code appropriate to its context. ; 
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7. Last I/O Status Code — The most recent I/O status code returned by a Form 
Driver call in your program 


The Form Driver handles this code the same way it handles the last status 
code. 


8. Current Library Channel — The I/O channel to be used any time your pro- 
gram needs access to the associated form library 


For example, you might want to open or close a form library or to retrieve a 
form for processing. The Form Driver uses the current library channel. 
The current library channel is associated with the current terminal. 


9. Supervisor-Only Flag — The flag used to control the processing of fields 
having the Supervisor Only attribute 


This flag is associated with the current terminal and is undefined if the 
current terminal is undefined. The supervisor-only flag is on by default. 


10. Timeout Value — The time (in seconds) that an operator has to respond 
(with each typed character) to a call for input from a terminal 


If the operator fails to respond within the specified time, the call is 
aborted. This value is associated with the current terminal and is ini- 
tially zero, meaning no timeout limits are in effect. The timeout value is 
undefined if the current terminal is undefined. 


11. Current Signal Mode — The mode in which the Form Driver gets an oper- 
ator’s attention 


Two modes are available to you — ringing the terminal bell and reversing 
the screen video. The reverse-video signal continues until the operator 
types a valid character. The current signal mode is associated with the 
current terminal. The default mode is to ring the bell (the only mode for 
VT52 terminals). : 


1.12 Operator Aids 
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1.12.1 . Help 


When the Form Driver is waiting for input, the operator can request help by 
pressing the Help key. Either a help form or a single line of help is available. 
In either case, the help supplied is specified when the form is designed. Sin- 
gle-line help messages remain on the bottom line of the screen until the oper- 
ator presses another key. 


If a help form is displayed, the Form Driver waits for the operator to press the 
ENTER key before reconstructing the original screen. If the operator presses 
the Help key again, instead of ENTER, additional help is displayed if it is 
available. Any other input is ignored. (The terminal bell rings or the screen 
video reverses if input has been rejected.) 
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1.12.2 Screen Refresh 


By pressing the Refresh key, the operator can update the screen image. That 
is, the screen is cleared, and all forms attached to the terminal and displayed 
are redisplayed. Forms no longer attached to the terminal or marked as not 
displayed, that were on the screen from a previous display call, are not redis- 
played. (You can also issue a RFRSH call from your program.) 


A screen refresh also restores the keypad mode, provided your program has 
previously issued a SPADA call (the Form Driver does not otherwise know 
the keypad state). The refresh operation also restores the terminal LEDs to 
the state they were in before the refresh occurred. 
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Chapter 2 
Form Driver Interaction 


The Form Driver interacts with your program and with terminals associated 
with the Form Driver. Discussion of such interactions is concerned with the 
degree of control your program has in: 


e Manipulating forms internally 
e Displaying forms on the terminals 


e Soliciting terminal operators’ responses to requests for field-by-field form 
data 


Some limitation is imposed on both your program and the operator prior to 
run time, by the way the forms are designed. Thus, for example, field attrib- 
utes are already assigned for forms, as is the order in which fields are 
processed in some calls. 


Other considerations are concerned with: 
© Who has control over the modification of fields in a form, and when 
e How control is passed to a terminal operator 


e When different levels of help for fields and forms are displayed for an 
operator 


e What keys and keypad layouts can be made available to an operator on 
VT100-/VT200- and VT52-compatible terminals. 


2.1 Interaction with the Form Description 


2.1.1 Storing and Accessing Form Descriptions 
Your program can store and access form descriptions in either of two ways: 


e As disk-resident forms, by reading them directly from a form library file 
that has been stored on a disk 


e As memory-resident forms, for which binary form descriptions (stored as 
object modules) are linked with the program : 
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Both ways make use of form descriptions that have been created with the 
Form Editor, Form Language Translator, Form Upgrade Utility, or Form 
Converter, and that have been processed with the Form Librarian or Form 
Application Aids. (See the VAX FMS Utilities Reference Manual.) 


For example, after using the Form Editor to create a form description, you 
must use the FMS/LIBRARY/CREATE command to store the description in a 
form library file or the FMS/MEMORY_RESIDENT command — a Form 
Application Aid — to produce an object module that permits access as a 
memory-resident form. You must then link the object program with the Form 
Driver and any other object modules you want to reside in memory, in order to 
form the executable FMS application program. (See Figure 2-1.) 


NOTE 


It is not necessary to build a single large object module con- 
taining all memory resident forms for an application. Multiple 
memory resident form objects produced by FMS can be linked 
into an executable image. 


Memory- UAR vector 
resident module 
forms 

™~ 






UAR object 
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Form library 


Figure 2-1: Building an Application Program 
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2.1.2 Displaying a Form 


There are three ways you can access a form. The method you use depends on 
where the form description resides: 


e Resides only in the form library 
e Resides in the form library, but is made memory resident at run time 


e Is linked with the application program and is memory resident at all times 
during program execution 


Form Characteristics 


A typical procedure for displaying a form at the beginning of an FMS applica- 
tion is: 


1. Make a terminal known to the Form Driver. (Use the ATERM call.) 


2. Allocate an internal storage area — form workspace — in which the Form 
Driver is to store the form description, including field values and other 
form requirements. (Use the AWKSP call.) 


3. If the form is disk resident: 


e Identify the I/O channel the Form Driver is to use for reading form 
descriptions from the form library file. (Use the LCHAN call.)! 


e Open the form library file. (Use the LOPEN call.) 


4. If you want that disk-resident form to become memory resident, read the 
form description into memory. (Use the READ call.) 


5. Display the form. (Use the CDISP or DISP call if the form description is 
disk resident.) 


The Form Driver provides two calls that both load workspaces and display 
forms — CDISP and DISP. The CDISP call clears the entire terminal screen 
before displaying a form. The DISP call clears only the screen lines that are 
required by the form, in its description, that you want to display. 


If you use short forms, you can use the DISP call to create for the operator a 
screen display that is composed of more than one form or part of a form. In 
such an instance, only one form would normally be active for the operator, 
although you could use special techniques like those described in Chapter 3 to 
switch back and forth among forms. 


For each call to display a form, the Form Driver checks the set of memory- 
resident forms first. When memory-resident and disk-resident form descrip- 
tions have the same form name, the Form Driver uses only the memory-resi- 
dent version. 


You can load a form from any source into a workspace, but not display the 
form on the terminal screen, by issuing the LOAD call. You can then put val- 
ues in fields of the form and display the form later by means of the DISPW 
call. Use of these calls may reduce the amount of output to the screen, since 
the fields of the form do not have to be written twice — once with the default 
values and once with the application-defined values. 


The name that you assign to a form with the Form Editor or Form Language 
Translator is the only information that the Form Driver needs to read the 
form from its form library file or to find its memory-resident description. Sim- 
ilarly, the name that you assign to a field is all the Form Driver requires, 
regardless of where you locate the field within the form. As long as changes to 
form and field characteristics have no effect on the logic of your program, you 
can change the characteristics without having to modify your program. 


1. You can eliminate this step if you include the I/O channel as an input argument in the 
following LOPEN call. 
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The following is a description of the screen management role of the Form 
Driver when overlaid forms are present and when your program issues PUTL 
and GETDL calls to reference lines that are parts of forms. Whenever the 
Form Driver is directed to output a value to the screen by a PUT-type field 
call — PUT, PUTAL, PUTD, PUTDA, or PUTSC — or is directed to request 
input from the operator by a GET-type field call — GET, GETAF, GETAL, or 
GETSC — it first checks to see if the form containing the field is still intact on 
the screen. If the form has been disturbed, part or all of it is redisplayed. 


A form is disturbed in one of two ways: 


1. Part of it has been overlaid by another form in a subsequent DISPW call, 
RFRSH call or operation, or help request. 


2. Part of it has been overlaid by a PUTL or GETDL call. 


No matter what part of the form has been overlaid, the form can be redis- 
played in its entirety. 


The Form Driver functions as a screen manager. It keeps track of every line 
on the screen belonging to every displayed workspace. Whenever a line is 
altered through the calls CLEAR, PUTL, GETDL, DISPW, CDISP, or DISP, — 
the Form Driver knows that the line has been affected. If the line is affected 
by PUTL, GETDL, or CLEAR, the Form Driver knows that the line has been 
completely cleared. 


If a line is overlaid by the display of another form that clears some lines, then 
those cleared lines are noted. (A form that overlays another form, without 
clearing lines, is assumed not to interfere with the underlying form. A form 
interferes with another form only if it has area-to-clear lines, and then it 
interferes only with those lines.) 


The Form Driver checks the lines of the form when information is sent to a 
screen field (by a PUT-type call), when information is requested of the screen 
(by a GET-type call), when help and UAR processing terminates, or when a 
new form is displayed. If any line has been cleared, as described above, the 
Form Driver rewrites all the affected lines of the screen by calling 
FDV$FIX_SCREEN internally. Thus, your program need do nothing if the 
screen has been affected by calls on the Form Driver, since the Form Driver 
knows and will fix the screen before the next I/O operation affecting fields. 


The Area to Clear attribute of a form is included in the description of the 
form. Therefore, at design time, the form designer should consider how much 
of the screen should be included in this attribute. Even if the form does not 
specify text or fields for a line, the Area to Clear attribute may specify that 
the line be blank when the form is displayed. 


The Form Driver honors the form description whenever the form is refer- 
enced. Ifa form is being redisplayed unexpectedly, it is most likely that part of 
the form has been overwritten. 
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2.1.3 Terminal Control 


Your application program can use either VT100-/VT200- or VT52-compatible 
terminals to display forms and to solicit responses from a terminal operator. 
Before you can use any terminal to display a form, you must first attach it to 
the application program by issuing an ATERM call. 


More than one terminal can be attached to an application program, but only 
one terminal at a time can be performing I/O operations. That terminal is 
called the current terminal. Other attached terminals continue to display 
any images already on their screens. 


At run time, the Form Driver keeps a list of all terminals attached to the 
application program. Form Driver calls can reference only terminals on this 
list; a few exceptions use the program’s default terminal. 


In an FMS application, a terminal control area (TCA) is reserved for each 
attached terminal. Once a TCA is initialized, the application program con- 
trols terminal activity by issuing calls that specify, implicitly or explicitly, 
the associated terminal control area. 


Form Driver calls that manage the initialization of terminals and their 
release are: 


ATERM Attach a terminal for use by an application program 
DTERM Detach a terminal from the list of attached terminals 
STERM Make the specified terminal the current terminal 


You should detach terminals before leaving FMS; otherwise, the terminals 
may continue to output assigned video attributes when they are no longer 
associated with FMS. If you do not explicitly detach a terminal from within 
- your program, video attributes assigned to the terminal remain in effect until 
you reattach the terminal and modify its attributes. 


2.1.4 Using Workspaces to Store Forms 


To process forms, your program must supply one or more workspaces in mem- 
ory. Each workspace can contain only one form description. Workspaces are 
internal to FMS and are inaccessible to the terminal operator. 


Each attached terminal can have one or more workspaces associated with it, 
but the Form Driver can access the form in only one workspace at a time — the 
current workspace. All other attached workspaces are considered passive at 
that time and can be used only for storing their form descriptions. 


Each workspace can be associated with only one terminal at a time. That is, 
no workspace can be simultaneously associated with more than one terminal. 
For example, if you want to display a form on two terminals at the same time, 
you must provide different workspaces for them and load the form into both 
workspaces. 
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An advantage of using multiple workspaces is to allow the simultaneous con- 
trol of multiple forms on the screen. For example, you can display a form 
stored in one workspace, switch to another form workspace by issuing a 
SWKSP call and display the form stored there either at the location specified 
at form definition time or at a screen location appropriately positioned by 
means of an “offset” argument in the display call. The Form Driver maintains 
the context of each workspace including, for example, the current field name. 


Ascreen refresh under application control — issuing a RFRSH call — or under 
operator control — pressing CTRL/R or CTRL/W — clears the screen of all text 
and redisplays all forms currently marked as displayed for the current 
terminal. 


The Form Driver supports calls that associate workspaces with terminals, — 
load workspaces with form descriptions, display forms from workspaces, and 
release workspaces. These calls are: 


AWKSP Attach a workspace to a terminal control area. 


CDISP Clear the screen and load a workspace with a form from a library or 
a memory-resident form list; then display the contents of the work- 
space. (The form is marked as being displayed for a later refresh 
operation.) 


DISP _— Load a workspace with a form from a library or a memory-resident 
form list; then display the contents of the workspace. (The form is 
marked as being displayed for a later refresh operation.) —~ 


DISPW Display the contents of a workspace. (The form is marked as being 
displayed for a later refresh operation.) 


DWKSP Detach a workspace from the list of attached form workspaces. 


LOAD Read a form description from the library or memory-resident list 
into the form workspace. 


NDISP Mark a form as being not displayed, but do not delete it from the 
workspace. (“Not displayed” means not displayed in a refresh oper- 
ation.) 


SWKSP Make the specified workspace the current workspace. 


You can detach workspaces either individually by issuing a DWKSP call or 
collectively by issuing a DTERM call. 


Figure 2—2 shows two VT100-compatible terminals attached to an FMS 
application. Each terminal must be attached by an ATERM call to the Form 
Driver in the application program before being used by a terminal operator. 
Each terminal has attached to it any number of workspaces. Each workspace 
can store one form description and must be attached to a specific terminal by 
an AWKSP call before a form description can be stored in it. 
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Figure 2-2: Attached Terminals and Related Form Workspaces 
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You maintain control over which form is being updated by specifying the cur- 
rent terminal and the current workspace. The STERM call specifies which 
terminal is the current terminal. The SWKSP call specifies which of that ter- 
minal’s workspaces contains the form description to be updated. 


To work on a different form in a workspace attached to a terminal that is not 
the current terminal, you need issue only a SWKSP call, since the Form 
Driver automatically switches to the associated TCA. For example, if the cur- 
rent workspace is workspace 1B and you want to address the form in work- 
space 2C, you issue the following: 


CALL FDVSSWKSP (WKSP2C) 


You can determine the current terminal and workspace at any time by issu- 
ing a RETCX call to ensure that the proper form is being updated. 


2.1.5 The Help Function 


Whenever your program issues a call for an operator response, the Form 
Driver can display two levels of help if the operator requests it — help for the 
field in which the cursor is located and help for the entire form. When the 
operator presses the Help key once, the Form Driver displays the help text 
that was specified as a field attribute, if any was specified. Then, when the 
operator presses the help key again, the Form Driver displays the Help form 
that was specified as a form-wide attribute, if any was specified. 
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The operator can erase any help form and have the Form Driver restore the 
original form at any time. The cursor’s position in the original form and all 
field values are unchanged. If the help form does not overlay the current form, 
the current form remains on the screen. Otherwise, the help form replaces the 
portion of the current form that it overlaps. 


For each form in your application, both the help text for fields and the help 
forms have to be specified when the form is created or changed with the Form 
Editor or the Form Language. Help forms for any disk-resident forms must be 
stored in the same form library file as the latter. 


2.1.6 Field Processing Order 


The Form Driver processes multiple fields of a form in the order specified in 
the form description. This order determines where “next” and “previous” 
functions take the cursor when the operator presses the corresponding keys 
to move from field to field. It is also the order in which field values are 
returned in GETAL, PUTAL, RETAL, GETSC, and PUTSC calls and the der- 
ivation of “first” and “last” fields in forms and scrolled lines. 


Your program can, nonetheless, control the order in which the operator works 
with fields. Your program can completely control the access order by issuing a 
GET call to get the value of a specified field. By repeating this call and speci- 
fying different fields, your program requires the operator to complete the 
fields in the order specified. 


Your program can allow the operator partial control by issuing the GETAF 
call, which allows the operator to choose any field in the form. The operator 
can respond in only one field, but it can be any modifiable field in the form. 
Since this call also identifies the name of the completed field, your program 
can then direct the operator to any other field. 


Your program can allow the operator complete control over the order of modi- 
fying fields by issuing GETAL, the call for all field values. But the Form 
Driver returns the field values to your program in a single character string 
with fields appearing in the order specified in the form description. The Form 
Driver returns to your application when the operator signals that the entire 
form is complete. 


In the returned field values, the length of each field value is the full length of 
the field. If the operator enters a value that is shorter than the field, that 
value is padded out to the field length with the fill character assigned to the 
field. For a right-justified field, the fill characters precede the value; for a left- 
justified field, they follow the value. 


Two calls, PUTAL and PUTSC, output more than one field value. The PUTAL 


. call specifies new workspace values for all fields in the form and displays the 


values if the form is displayed. The PUTSC call loads the workspace and dis- 
plays the field values for one line of a scrolled area. 


In both PUTAL and PUTSC, a single character string of field values is writ- 
ten in the order specified in the form description. 
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2.1.7 Text, Field-Marker Characters, and Video Attributes 


After displaying a form, the Form Driver normally is concerned with only the 
information that relates to the fields, such as the field picture, the fill and 
clear characters, the default value, and the line of help information. Unless 
the operator presses the Refresh key, the Form Driver makes no further use of 
information that is not related to the fields, such as the text in the form, the 
field-marker characters, or the video attributes of the characters displayed. 


In particular, the field values that the Form Driver returns do not contain any 
of the field-marker characters that the operator sees, such as the hyphen, dec- 
imal point, slash, and minus sign. In addition, the field values that your pro- 
gram passes to the Form Driver to display must not include field-marker 
characters. These field-marker characters are used for display only. They 
identify certain positions within a field. 


2.1.8 Processing Fields 


2.1.8.1 Field Pictures — The Form Driver checks the field pictures only when 
the operator is typing field values. The values that your program passes to the 
Form Driver for display are not checked for correspondence with the field 
pictures. 


When the operator is responding, a field picture is used to: 


e Check that each character satisfies the requirements of the picture charac- 
ter at the corresponding position. For example, in a field that has the mixed 
picture 999AAA, the Form Driver accepts only digits in the first three posi- 
tions and only letters in the last three positions. . 


e Limit the operator’s use of the Insert and Overstrike modes of entering field 
values. For example, the operator cannot change the combination of modes 
used for a fixed-decimal field or use Insert mode when completing a field 
that has a mixed picture. | 


2.1.8.2 Right Justified and Left Justified Field Attributes — The Form Driver 
uses the Right Justified and Left Justified attributes to: 


e Determine the position of the cursor when it is first displayed in a field. 


e Align the field value both on the screen and in the form workspace when 
the value is shorter than its field. The value in a right-justified field always 
ends at the rightmost character position in a field; the value in a left-justi- 
fied field always starts at the leftmost character position in a field. 


@ Determine when the operator has filled a field if the field has the Autotab 
attribute. 


e Set the default mode of entering values in a field. Insert mode is the default 
for a right-justified field, and Overstrike mode is the default for a left-justi- 
fied field. . 
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2.1.8.3 Clear Character and Fill Character Attributes — The Clear Character 
and Fill Character attributes affect the way fields whose values do not fill the 
field are padded on the screen and in the form workspace. The clear character 
is displayed, and the fill character is inserted as padding in the form work- 
space. A field with no value is displayed with only the assigned clear charac- 
ter and is stored in the form workspace with only the assigned fill character. 


Where padding an input field value is necessary, the Zero Fill attribute 
directs the Form Driver to pad with zeros in the form workspace. If Zero Fill is 
not specified, space characters are used to pad in the workspace. 


The clear character can be any printing character. 


2.1.8.4 Default Field Value — When you display a form, the Form Driver dis- 
plays the default field values and stores them as the current field values in 
the form workspace. But the Form Editor, the Form Language Translator, 
and the Form Driver do not check the default values. 


Although the Form Editor and the Form Language Translator allow you to 
assign the numeric default value 13467 for a field with the picture AAAAA, 
for example, and the Form Driver displays such a value, the Form Driver does 
not allow the operator to enter the value. Therefore, when developing your 
application, you must check that the default value is proper for the field. 


2.1.8.5 Autotab Attribute — When the operator types the character that fills a 
field having the Autotab attribute, the Form Driver terminates the field as if 
the operator had pressed the Next Field key. (However, different terminators 
are returned for fields completed by the Autotab attribute and by the Next 
Field key.) 


If a field has the Autotab attribute, the Form Driver determines that the field 
has been filled as follows: 


e For a Must Fill attribute assigned to the field, the operator must have 
entered enough characters to fill the field. 


e For a left-justified field, the operator must have typed a character in the 
rightmost character position of the field. 


e For a right-justified field, the leftmost character position must contain a 
character other than the fill character. 


2.1.8.6 Response Required and Must Fill Attributes — The Form Driver checks 
the validity of an operator’s response in a field having the Response Required 
or Must Fill attribute. 


In a field that has the Response Required attribute, the field must contain at 
least one character other than the assigned fill character before the program 
will continue to the next field. 


In a field that has the Must Fill attribute, the field must contain nothing or 
must be filled completely. The Form Driver does not accept a field value that 
is shorter than the field length or a value that contains a fill character. 
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The occurrence of such checking depends on which call your program issues 
for an operator response. For the call to get all the form’s field values from the 
operator (GETAL), for example, the Form Driver checks the values for each of 
these fields when the operator terminates input to the field by pressing the 
Next Field key or the Enter Form key. In addition, when the operator presses 
the Enter Form key, the Form Driver checks all modifiable fields in the form. 


For other calls, the Form Driver checks the values only when the operator 
terminates the field with the Next Field key or the Enter Form key. 


2.1.8.7 Fixed Decimal Attribute — The Form Driver makes use of the Fixed 
Decimal attribute to: 


e Align the parts of the field value that are to the left and to the right of the 
decimal point. The Form Driver retrieves input from the part to the left of 
the decimal point as a right-justified field and the part to the right as a left- 
justified field. . 


e Determine the fill and clear characters for the left and right parts of the 
field. The Form Driver displays the part to the right of the decimal point as 
if it were in a zero fill, clear character zero, and left-justified field, regard- 
less of whether the Zero Fill or Clear Character attribute is assigned. 


The Form Driver applies the assigned Zero Fill or Clear Character attri- 
bute only to the part of the value that is to the left of the decimal point. Note 
that if the fill character for the field is not zero, the Must Fill attribute 
requires entry and does not allow the usual option of leaving the field 
empty. . 


e Determine the position of the cursor when it is first displayed in a field. The 
cursor is placed at the decimal point, the hanging cursor position for the left 
part of the field. Output to fixed-decimal fields is treated as if the field were 
right justified. Such output should not include the decimal point, which is a 
field marker in fixed-decimal fields. 


2.1.8.8 Display Only Attribute — Fields having the Display Only attribute 
allow you to display their values without letting an operator enter new val- 
ues. The Form Driver does not allow the operator to position the cursor in a 
display-only field. When the operator presses the Next Field or the Previous 
Field key to move the cursor from field to field, the cursor jumps past display- 
only fields as if they were part of the form’s background text. Note, however, 
that data values of these fields are returned from calls such as GETAL and 
RETAL. 


2.1.8.9 No Echo Attribute — The Form Driver uses the No Echo attribute to 
prohibit field values from being displayed in fields. Not even the clear charac- 
ter or assigned video attributes are displayed in that field. When the operator 
enters a value in an No Echo field or when your program issues a call to dis- 
play a field value in an No Echo field, the Form Driver returns the field value 
to your program and stores it in the form workspace but does not display it. 
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2.1.8.10 Supervisor Only Attribute — When your program uses the SPON call 
to turn on the supervisor-only mode, the Form Driver prevents the operator 
from entering values for fields that have the Supervisor Only attribute. After 
your program issues the SPON call, the Form Driver treats all fields that 
have the Supervisor Only attribute as display-only fields. This state, which 
remains in effect until you issue the SPOFF call, applies to all forms that are 
displayed on a given terminal. When the program issues the SPOFF call, the 
Form Driver ignores the Supervisor Only attribute until the program issues 
the SPON call again. | 


The initial state for a terminal is SPON. Thatis, when a terminal is attached, 
its supervisor-only flag is turned on, thereby disallowing input to fields hav- 
ing the Supervisor Only attribute. 


2.1.8.11 Scrolling — Although the Form Editor, the Form Language Trans- 
lator, and the Form Driver do not allow you to use a form that is longer than 
23 screen lines, these components allow you to define sections within a form 
for displaying portions of large data tables. 


A data table is called scrolled because you can “roll” it upward or downward 
to display the lines that you want the operator to see or to work on. A scrolled 
area is a window into a form, showing a relatively large amount of data a few 
lines at a time. 


A scrolled area can be as small as one line. Within one form you can define as 
many separate scrolled areas as will fit within 23 lines. Each line can have as 
many separate fields as will fit on one screen line. Within each scrolled area, 
however, all lines must be identical with respect to the number, size, and 
attributes of fields and all other details. 


Because the Form Driver can store field values only for the fields that are on 
the terminal screen, your program must maintain all scrolled area field val- 
ues that are not displayed — that is, all the values that are “above” and 
“below” each scrolled area. When your program scrolls the lines of a scrolled 
area upward or downward, the program must collect the lines of values 
scrolled out of the area and display any line of values scrolled into the area. 


Chapter 3, Programming Techniques and Examples, includes some program- 
ming examples of scrolled area use. 


2.1.8.12 Date and Time Attributes — Ifa field has one of these attributes, the 
Form Driver automatically displays the system date or time in the field 
either when the form is loaded or at any other time when the field default is 
loaded. The date or time is updated whenever the field default is explicitly 
loaded; a PUTD or a PUTDA call causes the update, whereas a RFRSH call 
does not. 


Note that only the field default processing is affected; you cannot supply a 
field default for such a field. You can supply any other field attributes and 
process the field the way you want, but whenever the field default is displayed 
by the Form Driver, the date or time is displayed. 
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2.2 User Action Routines 


A user action routine (UAR) is a subroutine that provides special processing 
during the execution of an FMS application program. A UAR is not in-line 
code; rather, it is often coded and compiled separately from your program and 
is called from the Form Driver. A UAR’s object code is later linked with your 
program’s .OBJ file to form the executable run-time module. 


Each UAR is associated with a form or with fields within a form. When a form 
is designed, the form designer can request that the UAR be called whenever 
an application program processes that form or field. Then, during execution 
of the application program, the UAR is automatically called when the termi- 
nal operator presses: 


e A field terminator key to signal termination of a field or a form (called a 
field completion UAR) 


e The Help key (called a help UAR) 
e A function key that is not reserved for FMS (called a function key UAR) 


When the UAR ends, it returns a completion code to the Form Driver, indicat- 
ing whether the routine executed successfully or failed. A UAR can include a 
return context call (RETCX) to the Form Driver to get any current context 
information it might require or any other Form Driver call — for example 
RET — to get values of fields. 


The following actions are required before a user action routine can be used: 


1. The form designer must use the Form Editor or the Form Language 
Translator to assign a name and associated parameters to the UAR. 


2. The form designer must use the appropriate Form Application Aid to 
create a UAR vector module. 


3. The application programmer must code the procedure that the UAR is to 
perform. 


4. The application programmer must link the object module containing the 
names of all UARs to be called with the application program. 


2.2.1 Field Completion UARs 


A field completion user action routine is a function routine that is executed at 
run time whenever the operator finishes entering data in a field — that is, 
when an Autotab field has been filled or a field terminator key has been 
pressed. | 


A field completion UAR is not called under these conditions: 
e The field terminator is Previous Field 
e The terminator is a function key not reserved for FMS 


e The field was terminated with an illegal terminator (see description of 
ILTRM) 
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(A function key transformed into a Next Field or an Enter Form terminator 
by a function key UAR does, however, cause a field completion UAR to be 
called.) : 


During the Assign phase of the Form Editor or in using the Form Language 
Translator, the form designer can identify the name of the UAR and a param- 
eter associated with it. The parameter is a string of up to 80 characters. 


Each modifiable field in the form can have up to 15 field completion UARs 
associated with it. During program execution these UARs are executed each 
time the operator finishes entering data in a field. 


A field completion UAR is also called when your program issues a PFT call 
with a terminator code of FDV$K_FT_NTR. This facility lets your program 
check the validity of each nonscrolled field, just as the Form Driver checks 
operator data entry for Response Required or Must Fill fields. Note that in a 
GETAL call, the Ente r Form function causes the Form Driver to call all field 
completion UARs for nonscrolled fields. 


All field completion UARs are functions that return status codes. These codes 
indicate whether or not a UAR performed successfully. The status codes 
returned by the UAR and the corresponding actions that the Form Driver 
performs are listed below. The Form Driver interprets any other code as a 
programming error, terminates the GET-type call, and returns a status code 


of FDV$_UAR. 


Status codes returned by UARs do not comply with VMS coding standards 
(for cross-system compatibility reasons). 


If a timeout occurs or a CANCL call is issued while the operator is performing 
a field input operation, the input operation ends immediately, no field comple- 
tion UARs are called, and any field value returned is undefined. 


FDV$K_UVAL_FAIL Field validation failure. The Form Driver assumes 
that the field data is in error and requires that the 
field be reentered. This is the same condition that 
occurs when the operator types a character that 
does not agree with the field picture; the Form 
Driver rejects the input, and the operator is 
required to reenter the data. No further UARs 
associated with this field are called if this code is 
returned. 


FDV$K_UVAL_SUC Field validation success; continue processing. The 
Form Driver calls any additional action routines 
associated with this field. If no more exist, the 
Form Driver completes the field entry normally. 


If there is no field entry UAR, the Form Driver acts 
as if one were called and returns this completion 
code. | 
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FDV$K_UVAL_END 


Field validation success; end further processing of 
the field. No more UARs associated with this field . 
are called, and the field processing terminates nor- 
mally. 


See Chapter 3 for examples of field completion UARs. 


2.2.2 Help UARs 


The operator requests help by pressing the key designated as the Help key. 
There are two times during the processing of help that a UAR can be called. 
Before the normal Form Driver-supplied help processing begins, the ‘ ‘pre- 
help” UAR is called. After the normal Form Driver-supplied help processing 
is exhausted, the “post-help” UAR is called. 


2.2.2.1 Pre-Help UAR — A pre-help UAR is called to allow your help text to 
intercept any help processing provided by FMS. Based on the completion code 
returned by the UAR, the Form Driver acts as follows: 


FDV$K_UHELP_NO 


FDV$K_UHELPED 


FDV$K_UHELP_ALL 


The Form Driver assumes that no help processing 
was performed and proceeds with the normal help 
processing. That Help was pressed once already is 
recorded, and any subsequent pressing of the Help 


key does not result in the Form Driver’s calling the 


pre-help UAR again. 


If no pre-help UAR was specified for the form, the 
Form Driver acts as if one were called and returns 
a code of FDV$K_UHELP_NO. 


The Form Driver assumes that help was given by 
the UAR and provides no further help processing 
for the request. The Form Driver notes that the 
operator has pressed the Help key at least once for 
the current field. Any subsequent pressing of the 
Help key does not, therefore, result in the Form 
Driver's calling the pre-help UAR again. 


The Form Driver assumes that help was given by 
the UAR and provides no further help processing 
for the request. The Form Driver does not record 
that the operator pressed the Help key once 
already, and therefore any subsequent pressing of 
the Help key results in the Form Driver’s calling 
the pre-help UAR again. This completion code 
allows a UAR to take over all help processing by 
ensuring that every time the Help key is pressed, 
the pre-help UAR is called. 


The Form Driver interprets any other code as a programming error. The 
GET-type call or the WAIT call is terminated, and a status code of 


FDV$_UAR is returned. 
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2.2.2.2 Post-HelpUAR — This UAR is called to allow your program to supply 
some form of additional help after the the Form Driver-supplied help 
messages are exhausted. Based on the UAR completion code returned, the 
Form Driver does the following: 


FDV$K_UHELP_NO The Form Driver issues its HELP EXHAUSTED 
message. If the operator presses the Help key 
again, the help sequence starts over again. 


If no post-help UAR was specified, the Form Driver 
acts as if it called one and returns a completion 
code of FDV$K_UHELP_NO. 


FDV$K_UHELPED The Form Driver assumes that the post-help UAR 
has provided additional help information to the 
operator. If the operator presses the Help key 
again, the help sequence starts over again. 


FDV$K_UHELP_ALL The Form Driver assumes that the post-help UAR 
has provided additional help information to the 
operator. If the operator presses the Help key 
again, the UAR is called again. 


The Form Driver interprets any other code as a programming error. The call 
is terminated, and a status code of FDV$_UAR is returned. 


The Form Driver allows a depth of 15 in UAR nesting. Help is handled inter- 
nally as a UAR, so it contributes 1 to the nesting depth each time the HELP 
key is pressed. A pre- or post-help UAR adds another level to the depth. 


2.2.3 Help Request Processing 


When the Form Driver is processing an input call by your program, the opera- 
tor can request help from the system by pressing the Help key. The current 
request then stops, and the Form Driver acts as follows: 


1. If the operator has not previously pressed the Help key during the process- 
ing of the current field, the following actions occur: 


a. The Form Driver calls the pre-help UAR. If the UAR returns the status 
code FDV$K_UHELP_NO, the Form Driver attempts to display a sin- 
gle help line for the current field. (See the discussion of UARs above for 
information on UAR status codes.) If no help line exists for the field, the 
Form Driver goes on to step 2; otherwise, the Form Driver displays the 
help line, and processing of the the Help key is complete. The next time 
the operator presses the Help key, processing starts with step 2. 


b. If the UAR returns FDV$K_UHELPED as a status code, the Form 
Driver assumes that the normal single-line help is to be suppressed and 
that the UAR has provided separate help. As in step 1a, the next time 
the operator presses the Help key, the Form Driver begins processing it 
according to step 2. 
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If the UAR returns FDV$K_UHELP_ALL, the Form Driver again. 
assumes that no further help is needed, but in addition ends its progres- 
sion through the help support chain. When the operator presses the 
Help key again, the Form Driver processes the key according to step 1 
again. 


2. If step 1 has already been performed, either because a single-line help has 
already been given or because none could be given and the Form Driver 
proceeded automatically to this step, the following happens: 


a. 


If a help form is associated with the current form, it is displayed on the 
screen. Any subsequent pressing of the Help key begins processing 
according to step 3. 


. Ifno help form is associated with the form displayed, the post-help VAR 


is called. 


. If the UAR returns a status code of FDV$K_UHELPED, the Form 


Driver assumes that the UAR provided help in addition to the forms 
already displayed. Processing of subsequent pressing of the Help key 
resumes according to step 1. 


. If the UAR returns a status code of FDV$K_UHELP_ALL, the Form 


Driver assumes that the UAR provided help in addition to the forms 
already displayed. Processing of subsequent pressing of the Help key 
resumes according to step 2 again. 


. If the UAR returns a status code of FDV$K_UHELP_NO, the Form 


Driver assumes that the help available to the operator is exhausted and 
proceeds according to step 4. 


3. If the operator presses the Help key again, the following occurs: 


a. 


If a help form is associated with the Help form already on the screen, 
the new help form is displayed. Any subsequent pressing of the Help 
key begins processing according to step 3 again. (The help form on the 
screen may have been placed there either during step 2a or by a previ- 
ous execution of this step.) 


. Ifno help form is associated with the help form displayed, the post-help 


UAR is called. 


. If the UAR returns a status code of FDV$K_UHELP_ALL, the Form 


Driver assumes that the UAR provided help in addition to the forms 
already displayed. Subsequent pressing of the Help key resumes 
according to step 3 again. 


. If the UAR returns a status code of FDV$K_UHELPED, the Form 


Driver assumes that the UAR provided help in addition to the forms 
already displayed. Processing of subsequent pressing of the Help key 
resumes according to step 1. 


. If the UAR returns a status code of FDV$K_UHELP_NO, the Form 


Driver assumes that the help available to the operator is exhausted and 
proceeds according to step 4. 
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4. All help is presumed to be exhausted. The Form Driver prints a message 
indicating that no help is available. Any future Help key processing 
resumes according to step 1 again, allowing the operator to see the full © 
help sequence again. | 


Note that when a single help line is displayed, it is displayed on the bottom 
line of the screen and is removed from the screen the next time a key is 
pressed. When a help form is displayed, all or part of the screen — depending 
on the help form description — is first cleared. The help form is then displayed, 
and the Form Driver waits for the operator by executing a WAIT call until the 
operator presses either the Help key or one of the two default Enter Form 
keys, ENTER or RETURN. 


NOTE 


This is one of two occasions in the Form Driver — the other is 
when you are in Debug mode — that specify the ENTER key or 
the RETURN key as choices for the operator, rather than the 
more general Enter Form key, which could indicate a redefined 
alternate key. This arrangement guarantees that you can get 
out of help mode regardless of how you have redefined keys. 


If RETURN or ENTER is returned, the form in the current workspace is 
returned to its state prior to the displaying of help, and input processing is 
resumed. If FDV$K_FT_HELP is returned, the operator has pressed the 
Help key, and the Form Driver behaves according to the description above. 


A help UAR can change the screen by putting up new forms in workspaces 
other than the one current at the time of the UAR call. The Form Driver auto- 
matically restores the current workspace and redisplays the current work- 
space’s form if it is overlaid by UAR action. 


If a timeout or a cancel condition occurs during help processing, the call is 
terminated without restoration of any part of the screen. Your program can 
remove any single-line help from the bottom of the screen by issuing a PUTL 
call and can restore the rest of the screen by issuing a RFRSH call. 


Any call to a PUT or a GET function restores the current workspace’s form 
automatically. Thus, even with a timeout or a cancel condition, your program 
need not issue a RFRSH call if the same form and workspace are going to be 
used. 


2.2.4 Function Key UARs 


A function key UAR can be called whenever the operator presses a key not 
interpreted by FMS. Function keys include all nondata keys that are not 
FMS functions: control keys, special keys that produce escape sequences — for 
example, the Uparrow key — and Gold sequences, described later in this 
chapter. 
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FMS uses some of these keys for editing or for field terminators. You can rede- 
fine keys associated with these functions or delete the functions, thus freeing 
more keys for your program. See Section 2.4.2 for lists of all function keys. 


When the operator presses one of these keys during input to a GET-type call 
or a WAIT call and if the current workspace has a form in it that is marked as 
being displayed and that has a function key UAR, the Form Driver calls the 
function key UAR. Further processing depends on the value returned by the 
UAR, as listed below. 


If your program has requested that illegal terminators be returned to it 
instead of being signaled to the operator (see description of the ILTRM call in 
Chapter 5), the Form Driver also calls a function key UAR with the illegal 
terminator. (See Section 2.3.6.8.) 


The function key UAR can issue a RETCX call to determine which function 
key the operator pressed. 


Depending on the completion code returned by the UAR, the Form Driver 
acts as follows: 


FDV$K_UKEY_ERR ~The Form Driver assumes that no function is 
defined for the key, the pressing of the key is 
treated as an illegal keystroke, an error is sig- 
naled, and the key is ignored. No field completion 
UARs are called. 


FDV$K_UKEY_TRM The Form Driver resumes processing of the 
GET-type call or WAIT call, treating the function 
key as a key to be returned to your program as a 
terminator. That is, the code immediately termi- 
nates any input operation and is returned as the 
field terminator code. No field completion UARs 
are called. 


FDV$K_UKEY_NXT The Form Driver completes field or WAIT process- 
7 ing, treating the function key as if the operator 
had pressed the Next Field key. If the call is a 
GET-type call, Must Fill and Response Required 
attributes are checked, and field completion UARs 
are called next if any are defined for the field. If 
this function key results in completion of the 
entire call, Next Field is recorded as the field ter- 
minator character. 


Form Characteristics 2—19 


2-20 


FDV$K_UKEY_NTR = The Form Driver completes field or WAIT process- 
—_ ing, treating the function key as if the operator 
had pressed the Enter Form key. If the Form 
Driver is processing a GET-type call, Must Fill and 
Response Required field attributes are checked, 
and field completion UARs are called next if any 
are defined for the field. This completion code 
causes Enter Form to be recorded as the field ter- 
minator if the operator entered data that was rec- 
ognized as valid by the Form Driver. 


FDV$K_UKEY_SUC The Form Driver resumes processing of the WAIT 
or the current field, but otherwise ignores the key, 
assuming that the UAR successfully performed 
any processing associated with the key. No field 
completion UARs are called. 


The Form Driver interprets any other code as a programming error, termi- 
nates the GET-type call, and returns a status code of FDV$_UAR. 


2.2.5 Legal Actions in a VAR 


Your program can issue any Form Driver call from a UAR if you observe the 
following restrictions: 


1. You cannot detach the TCA or workspace that is current at the time the 
UAR is executing. 


_ 2. You cannot alter the current workspace by loading a new form into it. 


Your program can issue PUT or GET calls, switch to a new workspace, loada 
new form into a workspace, clear the screen, or take any action you might 
take ifno UAR were to be called. The Form Driver automatically restores the 
pre-UAR context after the UAR completes its execution. If a UAR changes 
the screen, the Form Driver ensures that the form in the current workspace is 
restored to the screen. 


The context restored by the Form Driver is: 
e Current terminal 

e Current workspace 

e Current field 


e Last terminator entered 
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Note that the Form Driver does not restore the current field’s cursor position 
or mode of character insertion (Insert or Overstrike). This condition allows a 
UAR to perform field editing and to reposition the cursor within a field before 
returning to the Form Driver. 


You should be very careful about performing input from a UAR, since this is 
recursive use of the Form Driver. It is easy to get into an infinite recursion by 
issuing a GET from a field that calls a field completion UAR that issues a 
GET, and so on. It is also important to be careful about issuing GET calls from 
a function key UAR, for the same reason. 


The Form Driver allows UARs to be nested to a maximum level of 15. Nesting 
to a deeper level causes an FDV$_UDP error to be returned to the call that 
generated the UAR. 


2.3 Interaction with the Terminal Operator 


The operator has no control until your program allows it by issuing one of the 
five Form Driver calls for an operator response: 


GET To get the value of a specified field 

GETAF To get the value of a single field that the operator chooses 
GETAL To get all field values for the current form 

GETSC To get all field values for a line in a scrolled area 

WAIT To wait for the operator to enter a terminator 


These five calls put the operator in control until the requirements of the call 
are satisfied. For example, after your program issues the GET call for the 
value of a specific field, the operator can type and make corrections. The oper- 
ator also can request help by pressing the Help key. It is only when the opera- 
tor terminates the field by pressing a field terminator key, such as the Next 
Field key, that the Form Driver returns control to your program. 


Each of the four GET-type calls also returns a status code indicating that a 
field has been modified — that is, that at least one character in the field has 
been entered or deleted during the processing of the call. Note, however, that 
if the operator enters a character and replaces it with the original value, the 
field is still considered modified. 


This section introduces the three kinds of operator activity: 
e Correcting errors and requesting help 
e Editing fields 


e Terminating and choosing fields 
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2.3.1 Signaling and Recovering from Errors 


The Form Driver responds to typing errors and invalid uses of the editing and 
field termination functions by signaling the operator and displaying 
messages on the bottom line of the screen. 


For all errors, the Form Driver either rings the terminal bell or reverses the 
video according to the signal mode that is in effect (see description of the 
SSIGQ call) and ignores the invalid character or function. The Form Driver 
also displays a one-line explanation at the bottom of the screen. For example, 
when an operator tries to enter a letter in a field that has been designed to 
accept only numbers, the Form Driver signals the operator and displays the 
following message: 


NUMERIC REQUIRED 


The Appendix of the VAX FMS Utilities Reference Manual lists and explains 
all messages that can appear. 


The Form Driver also provides a Debug mode of operation, which produces a 
set of error messages that help you in developing and refining your FMS 


application programs. If you are running your program in Debug mode and 


an error occurs as the result of a call on the Form Driver, the Form Driver 
stops your program, signals you, displays the Debug mode message on the 
bottom of the screen, and waits for you to press the ENTER or the RETURN 
key, regardless of how you have redefined any keys, before continuing execu- 
tion of your program. 


2.3.1.1 Help Key and Help Messages — The Help function can display two 
levels of information. 


When the operator presses the Help key for the first time, the Form Driver 
determines whether a help message exists for the current field. If such a one- 
line help message exists, the Form Driver displays it on the last line of the 
screen. The cursor remains in place within the field. 


If the one-line help message is not sufficiently helpful, the operator can press 
the Help key a second time. The Form Driver then determines whether a help 
form exists for the current form. 


If a help form exists, the Form Driver displays it while saving the context of 
the current form. Each help form can have yet another help form associated 
with it that is also displayed. 


The operator presses the Enter Form key to return to the original form. In 
response, the Form Driver restores the form and cursor to what they were 
before the Help key was pressed. 
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If no one-line help message for a field exists, the Form Driver displays the 
help form directly. When no more help is available, the Form Driver displays 
a message to that effect on the last line of the screen. When the operator next 
types a field terminator, the Form Driver clears the last line. 


Note that although this is the normal sequence for help processing, help 
UARs can alter it. See Section 2.2.2. 


2.3.1.2 Checking Operator Responses from Your Program — Your program 
must be responsible for checking operator responses at certain times. The 
Form Driver cannot distinguish valid operator responses from invalid ones in 
two instances. 


First, although the Form Driver accepts only the operator responses that 
meet the requirements of a field attribute that was assigned with the Form 
Editor or the Form Language Translator, the Form Driver cannot detect a 
field value that is invalid in your application. Second, when an operator uses 
certain function keys to terminate work with a field, the Form Driver does no 
field checking (Response Required, Must Fill, or Field Completion UARs), 
leaving that task to your program. 


In both of these instances, you can design your program to detect errors and 
other conditions and to display messages for the operator. Chapter 3 describes 
some processes and techniques. 


2.3.1.3 Refreshing the Screen: Typing CTRL/R — Hold down the CTRL key 
and press the R key on the keyboard. When the operator types this character, 
the Form Driver refreshes the screen. That is, the screen is cleared, and all 
forms currently marked as displayed are redisplayed. 


2.3.2 Field Editing Functions 


Table 2-1 summarizes the field editing functions that the Form Driver pro- 
vides and lists the default keys that control the functions. These functions are 
executed entirely by the Form Driver. You can implement additional func- 
tions for the operator by interpreting any function keys not used by FMS. 
Such functions are implemented by your program after the Form Driver 
returns control to it. 
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Table 2-1: Field Editing Keys, Functions, and Usage for the Form Driver 


Default Key 
Leftarrow 


Rightarrow 


DELETE 


LINEFEED or F13 
PF 1 or Blue 


PF1 DELETE or 
Blue DELETE 


PF1 PF3 or 
Blue Gray 


PFS or Gray 
PF, Red or Help 


CTRL/R 


Most 
keyboard 
keys 


Function 


Cursor Left 
Cursor Right 


Delete Character 


Delete Field 
Gold Key 
Reset 


Insert Mode 


Overstrike Mode 
Help 


Refresh Screen 


Insertion 


Usage 


Moves the cursor to the preceding data char- 
acter position within the field, skipping any 
field-marker character. 


Moves the cursor to the next data character 
position within the field, skipping any field- 
marker character. 


In Insert mode, deletes the character at the 
cursor’s left and closes the space. 


In Overstrike mode, moves the cursor to the 
preceding character position within the field, 
but deletes it only when the character is the 
last nonblank one in a left-justified field. 


Deletes the entire field and resets the mode of 
character insertion to the default mode for the 
field (Overstrike or Insert). 


Starts a Gold, or 2-character, sequence. Press- 
ing the Gold key several times is equivalent to 
pressing it once. 


Cancels a Gold sequence. If the operator can- 
not remember if a Gold sequence was started, 
this sequence safely allows the retyping of the 
function. 


Sets Insert mode. 


Sets Overstrike mode. 


First, displays the help text for the cursor’s 
field and then displays successive help forms 
for the current form. 


Refreshes the screen, with all forms marked 
as displayed. 


The keys for the printing characters on the 
keyboard insert their characters. In the nor- 
mal, or numeric, keypad mode, the numeric 
and punctuation keys on the keypad also 
insert their characters. 


2.3.2.1 VT100 Alternate Keypad Mode — Youcan set the VT100 terminal to an 
alternate keypad mode or back to a normal (numeric) keypad mode by issuing 
the SPADA call. Regardless of the terminal’s keypad mode, the editing and 


terminator functions remain the same. 


2.3.2.2 The Cursor’s Initial Position in a Field — The initial position of the cur- 
sor in a field depends on whether the field has the Right Justified, Left Justi- 


fied, or Fixed Decimal field attribute. 


For right-justified fields, the initial position is just to the right of the last 
character position in the field. This position is called the hanging cursor posi- 
tion because the cursor hangs off the end of the field. 
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For left-justified fields, the initial position is the leftmost character position 
in the field. 


The cursor’s initial position for a fixed-decimal field is the decimal point that 
the Form Driver displays. The decimal point is a field-marker character. It is 
not stored in the form workspace or returned to your program as part of the 
field value. 


The decimal point in a fixed-decimal field is the rightmost period or comma in 
the field, whichever one is in effect. Any other periods or commas are treated 
as normal field-marker characters. A comma is usually used as a decimal 
point in Europe, and a period is normally used elsewhere. 


The Form Driver treats the left part as a right-justified field and the right 
part as a left-justified field. With the cursor at the initial position, the Form 
Driver displays the first digits that the operator types in the part to the left of 
the decimal point until the operator types a decimal point. Then the Form 
Driver displays the digits that the operator types in the part of the field that is 
to the right of the decimal point. 


As the operator edits a fixed-decimal value, the Delete Field function deletes 
the entire value and returns the cursor to the initial position. The Delete 
Character function also deletes the digits in the field value. If the cursor is 
just to the right of the decimal point, however, the Delete Character function 
moves the cursor back to the decimal point but does not delete it. 


2.3.2.3. Inserting a Field Value: The Default Function — For VT100 keys the 
Form Driver accepts the standard letters, numbers, and special characterson _ 
_ the keyboard that meet the requirements of the field. | 


For the keyboard keys, insertion of values in fields is the default function. For 
the numeric and punctuation keys on the keypad, insertion is also the default 
when the keypad is in the normal, or numeric, mode. In both instances, the 
operator types values as if using a typewriter. 


Insertion is invalid only when it does not meet the field’s requirements. For 
example, letters are invalid where numbers are required. For a field that does 
not have the Autotab attribute, all characters are invalid when the field is 
full. 


2.3.2.4 The Signed Numeric Picture — A signed numeric picture is treated in 
two special ways by the Form Driver. One way allows for acceptance of an 
alternate character for the conventional decimal point. The default is for the 
Form Driver to allow the period in an N picture and to return it to your pro- 
gram as part of the value of the field. | 


For European-style decimal points, your program issues the DPCOM call 
with an argument of 1. The Form Driver then accepts the comma as the deci- 
mal point for the current terminal. After this call, only the comma is recog- 
nized as a decimal point in a signed numeric picture. Calling DPCOM with an 
argument of 0 reestablishes the initial decimal point character, the period. In 
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either case, the decimal point in signed numeric pictures is returned to your 
program as part of the field value, unlike the decimal point in fixed-decimal 
fields. 


The other special treatment is that the entry of a sign (+ or —) or a decimal 
point in a field position having an N picture causes the entire field to be 
checked for valid data. If the field already has a sign or a decimal point, the 
character is rejected. Thus, any field having an entire signed numeric picture 
is allowed only one sign and only one decimal point. (A mixed picture field 
could have more than one sign or decimal point if the additional signs or deci- 
mal points were entered into positions that were not signed numeric.) 


Note that the Form Driver does not check the position of a sign in a field con- 
taining a signed numeric picture; therefore, the sign can occur in the middle 
rather than at the beginning or the end of the field. You can write a field com- 
pletion UAR to enforce a particular position for the sign if your application | 
requires it. 


2.3.2.5 Deleting a Character 
e Default VT100 Key: DELETE 


The Delete Character function normally deletes the character that is to the 
left of the cursor. The function has different effects, however, in Insert and 


Overstrike modes. 


In Insert mode, the Delete Character function deletes the character to the left 
of the cursor and closes up the space. In a left-justified field, the value remains 
left justified; in a right-justified field, the value remains right justified. 


In Overstrike mode, the Delete Character function moves the cursor one 
character to the left. The function does not delete a character in Overstrike 
mode except when the character is the rightmost character entered in a left- 
justified field. 


The Delete Character function is invalid when the cursor is on the leftmost 
character in a field. 


2.3.2.6 Deleting a Field 
e Default VT100 Key: LINEFEED 
e Default LK201 Key: F13 


Regardless of the cursor’s position in a field, the Delete Field function deletes 
all characters in the field except field-marker characters. The Form Driver 
then displays the assigned clear character for the field and in the form work- 
space fills the field with the assigned fill character. When the function is com- 
plete, the cursor is at the initial position for the field — the leftmost character 
for a left-justified field, to the right of the rightmost character for a right-jus- 
tified field, and on the decimal point for a fixed-decimal field. In addition, the 
mode of character insertion is reset to the default mode for the field (Over- 
strike or Insert). 


The Delete Field function is always valid input in a field. 
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2.3.2.7 Moving the Cursor to the Right 
e Default VT100 Key: -—(Rightarrow) 


The Cursor Right function normally moves the cursor one character to the 
right within a field. However, the cursor always skips the field-marker char- 
acters, such as the hyphen (-) and the slash (/). 


The Cursor Right function is invalid when the cursor is to the right of the 
rightmost character in a field — that is, in the hanging cursor position. 


2.3.2.8 Moving the Cursor to the Left 
e Default VT100 Key: <~(Leftarrow) 


The Cursor Left function normally moves the cursor one character to the left 
within a field. However, the cursor always skips the field-marker characters 
in a field. 


The Cursor Left function is invalid when the cursor is on the leftmost charac- 
ter of a field. 


2.3.3 Switching the Insertion Modes 


© Default VT100 Keys: PF3 on the keypad for Overstrike 
PF 1 and PF3, in sequence, on the keypad for 
Insert 


While the operator is typing a field value, the Insert and Overstrike insertion 
modes control how the Form Driver displays the characters. For most of the 
different types of fields that can be designed, the operator can control the. 
insertion mode by using the Insert and Overstrike functions. 


When either the operator or your program first moves the cursor to a field, the 
Form Driver sets the insertion mode according to the attributes of the field. 
Insert mode is the default for right-justified fields, and Overstrike mode is the 
default for left-justified fields. 


While the operator types in the Insert mode in a left-justified field, the Form 
Driver inserts each character at the cursor’s position. The cursor, the cursor’s 
character, and all characters within the field that are to the right of the cursor 
are shifted to the right. In a right-justified field, all characters to the left of 
‘the cursor are shifted to the left, and the character is inserted to the left of the 
cursor. 


In Overstrike mode, the Form Driver replaces the cursor’s character with the 
character typed and moves the cursor to the right. 


In fields that have mixed pictures, Insert mode is invalid. In fixed-decimal 
fields, the Insert and Overstrike functions are ignored, because of the special 
data entry conventions that fixed-decimal fields require. In all other 
instances, the Insert and Overstrike functions are valid. 
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2.3.4 Field Terminators 


Each of the keys listed in Table 2—2 controls a field terminator. The Autotab 
field attribute also controls a unique terminator. When an operator presses a 
key that terminates a field or completes a field that has the Autotab attribute, 
the Form Driver either processes the terminator itself and displays the effect 
for the operator or returns a unique field terminator code to your program and 
leaves the processing to the program. Table 2—2 also gives the processing and 
code that the Form Driver uses for each field terminator key. 


When you set the VT100 keypad to alternate keypad mode, the Form Driver 
also treats the keypad’s numeric keys, comma key (,), hyphen key (-), and dec- 
imal point key (.) as field terminators. The codes for these alternate keypad 
mode terminators are returned to your program. In addition, keys not 
assigned to the Form Driver that are in the following groups are terminators: 
control keys, all 2-key sequences beginning with the Gold key — PF1 key by 
default — and all keys producing escape sequences, such as the Uparrow key. 


Table 2-2: Default Field Terminator Keys, Values, Symbols, and Effects 


Default Value Symbol Description 
Key (Decimal) 
ENTER 0 FDV$K_FT_NTR Terminates all entries in the form. If 
or RETURN the call being processed is a GETAL 
(Enter Form) and if required entries are not com- 


plete, the Form Driver refuses to 
accept the terminator, and the opera- 
tor remains in control. If required 
entries are complete, the terminator 
is returned to the program. There- 
fore, the final effect depends on the 
next call that the program initiates 
for an operator response. 


If any other call is being processed, 
only the requirements for the cur- 
rent field must be satisfied. In such 
an instance, control is returned to 


the program. 
TAB 1 FDV$K_FT_NXT Valid only when the current field is 
(Next Field) not the last modifiable field in the 


form. Moves the cursor to the initial 
position of the next field. 


Processed by the Form Driver for the 
GETAL and GETSC calls and, until 
an entry is typed or modified, for the 
GETAF call. Returned to the pro- 
gram for the GET call and, after an 
entry is typed or modified, the 
GETAF call. 


6 FDV$K_FT_SNX Scroll forward to the next field. The 
Next Field key or the Autotab attri- 
bute in a full field terminated input 
in the last field of a scrolled line. 
Always returned to the program. 


(Continued on. next page) 
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Table 2~2: (Cont.) Default Field Terminator Keys, Values, Symbols, and 


Default 
Key 


BACKSPACE 
or F12 
(Previous Field) 


None 
(Autotab) 


PF1 Uparrow 
(Exit 

Scrolled 

Area 
Backward) 


PF1 Downarrow 


(Exit 
Scrolled 
Area 
Fordward) 


FDV$K_FT_PRV 


FDV$K_FT_SPR 


FDV$K_FT_ATB 


FDV$K_FT_XBK 


FDV$K_FT_XFW 


Description 


Valid only when the current field is 
not the first modifiable field in the 
form. Moves the cursor to the initial 
position of the previous field. 


Processed by the Form Driver for the 
GETAL and GETSC calls and, until 
an entry is typed or modified, for the 
GETAF call. Returned to the pro- 
gram for the GET call and, after an 
entry is typed or modified, the 
GETAF call. 


Scroll backward to the previous field. 
The BACKSPACE key terminated 
input in the first field in a scrolled 
line. Always returned to the pro- 
gram. 


Valid only when the current field is 
not the last modifiable field in the 
form. Moves the cursor to the initial 
position of the next field. 


Processed by the Form Driver for the 
GETAL and GETSC calls and, until 
an entry is typed or modified, for the 
GETAF call. Returned to the pro- 
gram for the GET call and, after an 
entry is typed or modified, the 
GETAF call. 


Valid input only when the current 
field is in a scrolled area. Moves the 
cursor out of the scrolled area to the 
initial position of the previous field 


‘that the operator is allowed to com- 


plete. Invalid if the scrolled area has 
the first readable field in the form. 


Valid input only when the current 
field is in a scrolled area. Moves the 
cursor out of the scrolled area to the 
initial position of the next field that 
the operator is allowed to complete. 
Invalid if the scrolled area has the 
last readable field in the form. 


(Continued on next page) 
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Table 2-2: (Cont.) Default Field Terminator Keys, Values, Symbols, and 


Default 
Key 


Downarrow 
(Scroll 
Forward) 


Uparrow 
(Scroll 
Backward) 


Effects 
Value Symbol 
(Decimal) 
8 FDV$K_FT_SFW 
9 FDV$K_FT_SBK 


Description 


Valid input only when the current 
field is in a scrolled area. The scrol- 
led area is scrolled up, and the cur- 
rent line remains the same physical 
line, with new data, or the cursor 
moves down one line, and that line 
becomes the new current line. The 
cursor moves to the initial position of 
the first field that the operator is 
allowed to complete in the current 
line. When processed during a 
GETAF call, acts like Exit Scrolled 
Area Forward because GETAF oper- 
ates only on current scrolled line. 


Valid input only when the current 
field is in a scrolled area. The scrol- 
led area is scrolled down, and the 
current line remains the same physi- 
cal line, with new data, or the cursor 
moves up one line, and that line 
becomes the new current line. The 
cursor moves to the initial position of 
the first field that the operator is 
allowed to complete in the current 
line. When processed during a 
GETAF call, acts like Exit Scrolled 
Area Backward because GETAF 
operates only on current scrolled 
line. 


This section describes how your program can use the field terminators and 
Form Driver calls to guide an operator from field to field in a form in any 


order. 


1. Using the GETAL call 
e The program initiates the GETAL call. 


e The operator uses, at any time, the field terminator keys that move the 
cursor from field to field — nonscrolled fields only. The Form Driver 
processes these field terminators without returning them to the 


program. 


e When the operator presses the Enter Form key, the Form Driver checks 
for valid values for every nonscrolled modifiable field in the form. Ifa 
field value is found to be invalid, the Form Driver moves the cursor to 
the field, and the operator must enter an acceptable value. 


When all values are acceptable, the Form Driver returns the field termi- 
nator code and the string of field values to the program. If the operator 
presses any non-F'MS function key, no checking occurs, and the function 
key code and string of values are returned to the program. 


e The program is then in control of what the operator does next. 
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2. Using a series of GET calls 


e The program initiates the GET call. The operator can type and change 
only the entry in the specified field. The Form Driver checks for valid 
field data for any field but one terminated by a function key or the Previ- 
ous Field key. 


e When the operator presses a field terminator key, the Form Driver 
returns the field terminator code and the single field value to the pro- 
gram. The program then is in control of what the operator does next. For 
example, on the basis of the field value or the field terminator, the pro- 
gram can specify the same field or another field in the next GET call. 


2.3.5 Field Terminators and Form Driver Calls 


When your program issues a call to get an operator response, the Form Driver 
allows the operator to type an entry in a field or a terminator in response toa 
WAIT call. When the operator presses a field terminator key that completes 
the call, the Form Driver passes the field response and the field terminator 
code to the program and prohibits the operator from further typing. For a 
WAIT call, the Form Driver accepts any terminator or function key and 
returns it to your program. | 


Only the following four Form Driver calls allow the operator to respond in a 
field: 


GET To get the value and the field terminator for a specified field 


GETAF To get the value for any one field that the operator chooses, as well 
as the field name and the field terminator 


GETAL To get all field values for the current form and the last field termi- 
nator used 


GETSC _ To get all the field values from the current line of a specified 
_ scrolled area and the last field terminator used 


For each of these four calls, the Form Driver checks all field terminators. For 
example, with the cursor in the first field in a form, the Form Driver accepts 
the field terminator for the Next Field key but does not accept the field termi- 
nator for the Previous Field key. 


Table 2-3 lists the four calls and shows the field terminator keys that com- 
plete each call. | 


The GET call leaves control of responding to any field terminator to your 
program. 


The GETAF call solicits input for one field but returns control to the program 
as soon as the operator modifies a field and presses any field terminator key, 
or presses the Enter Form key or any non-FMS terminator key — CTRL key 
combination, function key, or Gold key sequence. (A non-F'MS terminator can 
always complete a call.) 


The GETAL call leaves the Form Driver in control of responding to any field 
terminator except when the operator presses the Enter Form key. 
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The GETSC call leaves the Form Driver in control within a line of a scrolled 
area until the operator presses the Enter Form key or any function key that 
results in an exit from the scrolled line. 


Table 2-3: GET-type Calls and Their Field Terminators 


Call Field Terminator Keys that Completé the Call 


GET Any valid field terminator key, the Autotab code, or any non-FMS key 


GETAF _ Enter Form key or any typed field entry followed by any valid field terminator key, 
the Autotab code, or any non-F'MS key 


GETAL Enter Form key or any non-FMS key 


GETSC Enter Form, Scroll Backward, Scroll Forward, Exit Scrolled Area Backward, Exit 
Scrolled Area Forward, Next Field (or Autotab) out of last field, Previous Field out 
of first field, or any non-FMS key 


The following principles summarize Tables 2—2 and 2-3: 


1. The effects of the field terminator keys cannot be changed from what 
DIGITAL has designed in the following calls: 


e GETAL 
e GETSC 
e GETAF before the operator makes a field entry 


2. When the operator presses the default Enter Form key or, in response to 
the GET call, any field terminator key, the program alone controls the 
effect that the operator sees. 


For example, if you use the GETAL call in a program, the Next Field key 
advances the cursor from field to field according to the order that is built into 
the form description. But if you use a series of GET calls instead of the 
GETAL call, the program is passed the field terminator code for the Next 
Field key and can react to it in any way you specify. 


Your program can, for example, issue the PFT call. After the operator uses 
any field terminator that returns control to the application program, the pro- 
gram can initiate the PFT call, making the Form Driver follow the effects of 
any field terminator key. In the example of a GET call terminated by the oper- 
ator’s pressing of the Next Field key, the program can react by specifying the 
Previous Field key in the PFT call. Then, the effect of the next GET call is to 
move the cursor back to the previous field in the form. 


Alternatively, your program can issue another GET call. In the example of a 
GET call terminated by a Next Field function key, the program can react with 
another GET call that specifies by name the next field that the operator is to 
complete, regardless of where the field appears on the operator’s screen. 
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2.3.6 Field Terminating Functions 


The operator presses terminator keys to move to new fields or a new form. 
How the Form Driver processes these functions depends on the current Form 
Driver call that is being executed. In many instances, the Form Driver gives 
your program an opportunity to intercept and change the terminator func- 
tion that the operator has used. The Form Driver identifies each terminator 
function by means of a unique terminator code. 


Because the Form Driver can be executed from either a VT52-, a VT100-, ora 
VT200-compatible terminal, a set of terms common to both devices is 
required to describe logical field terminating functions. In addition, since 
your program can modify the association between keys and functions, the 
field terminators are referred to by their functions rather than by the names 
of particular keys. 


Table 2-1 describes the relationship between the logical function keys 
referred to in this manual and their corresponding default physical keys on 
VT52-, VT100-, and VT200-compatible terminals, with an LK201 keyboard. 


2.3.6.1 Signaling that the Form is Complete 


© Default VT100/VT200 Keys: ENTER on the keypad 
RETURN on the keyboard 


e Terminator Code 


Value: 0 
Symbol: FDV$K_FT_NTR 


The Enter Form key signals that the operator has completed the current 
form. 


When a GETAL call is issued, the Form Driver does not accept the Enter 
Form key until all field values satisfy their field requirements. A Response 
Required field must have a response of at least one character, a Must Fill field 
must be either empty or filled, and all field completion UARs must return 
success values. 


For any other Form Driver call, control is returned to the program if the 
requirements for the current field value are satisfied. 

2.3.6.2 Moving the Cursor to the Next Field 

e Default VT100/VT200 Key: TAB 


e Terminator Code 


Value: 1 (when terminating a field outside of a scrolled area) 
‘Symbol: FDV$K_FT_NXT 
Value: 6 (when terminating a field at the end of a scrolled line) 


Symbol: FDV$K_FT_SNX 


The Next Field function is valid only when the requirements for the current 
field value — Response Required, Must Fill, or field completion UARs — are 
satisfied. 
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The effects of the Next Field function depend on the Form Driver call that is 
being executed. 


For the GETAL and GETSC calls and for the GETAF call before the operator 
enters or changes a field value, the Form Driver processes the function 
directly and moves the cursor to the initial position of the next modifiable 
field. 


For GETSC at the end of a scrolled line, control is returned to the program. 
For the GET call and for the GETAF call after the operator enters or changes 
a field value, the Form Driver transfers control to the program. The next call 
in your program determines what the operator sees. For example, after the 
operator terminates a field with the Next Field key, your program might dis- 
play a new form, calculate and display a value in a display-only field, or issue 
another call for another operator response in a specific field. 


The function is invalid when the cursor is in the last nonscrolled modifiable 
field of the form. 

2.3.6.3 Moving the Cursor to the Previous Field 

e Default VT100 Key: BACKSPACE 

e Default LK201 Key: F12 


e Terminator Code 


Value: 3 (when terminating a field outside of a scrolled area) 
Symbol: FDV$K_FT_PRV 
Value: 7 (when terminating a field at the beginning of a scrolled line) 


Symbol: FDV$K_FT_SPR 


The effects of the Previous Field key depend on the Form Driver call that is 
being executed. 


For the GETAL and GETSC calls and for the GETAF call before the operator 
enters or changes a field value, the Form Driver processes the function 
directly and moves the cursor to the initial position of the previous modifiable 
field. 


For GETSC at the beginning of a scrolled line, control is returned to the pro- 
gram. For the GET call and for the GETAF call after the operator enters or 
changes a field value, the Form Driver transfers control to the program. The 
next call in your program determines what the operator sees. 


The function is invalid when the cursor is in the first nonscrolled modifiable . 
field of the form. 
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2.3.6.4 Scrolling Backward 
e Default VT100/VT200 Key: (Uparrow) 
e Terminator Code 


Value: 9 
Symbol: FDV$K_FT_SBK 


The Scroll Backward key is valid only when the cursor is in a field that is 
within a scrolled area. For GETAF before the operator enters or changes a 
field value, the Form Driver processes the key directly and moves the cursor 
to the initial position of the first modifiable field before the scrolled area, as if 
the key were the Exit Scrolled Area Backward key. 


The function transfers control to your program for GET and GETSC and for 
GETAF after the operator enters or changes a field value. Therefore, you can 
choose to use the function in any way you want, and the effects that the opera- 
tor sees depend on the next calls that your program issues. 


The Form Driver processes the Scroll Backward terminator when you specify 
its code in the PFT call. The Form Driver either moves the cursor to the pre- 
ceding data line within the scrolled area and places the cursor at the initial 
position of the first modifiable field in that data line or scrolls the area back- 
ward and places the cursor at the initial position of the first modifiable field in 
the current line. 


When the cursor is on the top screen line of the scrolled area, or if the program 
specifies data to update the top line, the Scroll Backward function scrolls the 
bottom scrolled line of information off the screen, scrolls a new line of infor- 
mation into the top line of the scrolled area, and moves the intermediate 
scrolled lines downward. If the cursor is on the top line and if your program 
specifies values for the new line of information, they are displayed; otherwise, 
the default field values are displayed. 


The function is invalid when the cursor is in a field that is not within a 
scrolled area. . 


2.3.6.5 Scrolling Forward 
e Default VT100/VT200 Key: =} (Downarrow) 


e Terminator Code 
Value: 8 
Symbol: FDV$K_FT_SFW 


The Scroll Forward function is valid only when the cursor is in a field that is 
within a scrolled area. For GETAF before the operator enters or changes a 
field value, the Form Driver processes the key directly and moves the cursor 
to the initial position of the first modifiable field after the scrolled area, as if 
the key were the Exit Scrolled Area Forward key. 


The function transfers control to your program for GET and GETSC and for 
GETAF after the operator enters or changes a field value. Therefore, you can 
choose to use the function in any way you want, and the effects that the opera- . 
tor sees depend on the next calls that your program issues. 
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The Form Driver processes the Scroll Forward key when you specify its code 
in the PFT call. The Form Driver either moves the cursor to the next data line 
within the scrolled area and places the cursor at the initial position of the first 
modifiable field in that data line or scrolls the area forward and places the 
cursor at the initial position of the first modifiable field in the current line. 


When the cursor is on the bottom screen line of the scrolled area, or if the 
program specifies data to update the bottom line, the Scroll Forward function 
scrolls the top scrolled line of information off the screen, scrolls a new line of 
information into the bottom line of the scrolled area, and moves the interme- 
diate scrolled lines upward. If the cursor is on the bottom line and if your pro- 
gram specifies values for the new line of information, they are displayed; 
otherwise, the default field values are displayed. 


The function is invalid when the cursor is in a field that is not within a 
scrolled area. 


2.3.6.6 Exiting Scrolled Area Backward 
e Default VT100/VT200 Key Sequence: PF 1 followed by the Uparrow 


e Terminator Code 
Value: 4 
Symbol: FDV$K_FT_XBK 


The Exit Scroiied Area Backward key is valid only when the cursor is in a 
field that is within a scrolled area. The function transfers control to your pro- 
gram unless your program is executing a GETAF call and the operator has 


‘not yet entered or changed a field value. Therefore, you can usually use the 


function in any way you want, and the effects that the operator sees depend 
on the next calls that your program issues. 


The Form Driver processes the Exit Scrolled Area Backward key when you 
specify its code in the PFT call, except when your program is executing a 
GETAF call. The Form Driver moves the cursor to the initial position of the 
first modifiable field preceding the scrolled area. 


The function is invalid when: 
1. The cursor is in a field that is not within a scrolled area. 


2. No modifiable field precedes the scrolled area. 


2.3.6.7 Exiting Scrolled Area Forward 
© Default VT100/VT200 Key Sequence: PF 1 followed by the Downarrow 


e Terminator Code 
Value: 5 
Symbol: FDV$K_FT_XFW 


The Exit Scrolled Area Forward key is valid only when the cursor is in a field 
that is within a scrolled area. The function transfers control to your program 
unless your program is executing a GETAF call and the operator has not yet 
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entered or changed a field value. Therefore, you can usually use the function 
in any way you want, and the effects that the operator sees depend on the next 
calls that your program issues. 


The Form Driver processes the Exit Scrolled Area Forward key when you 
specify its code in the PFT call, except when your program is executing a 
GETAF call. The Form Driver moves the cursor to the initial position of the 
first modifiable field following the scrolled area. 


The function is invalid when: 
1. The cursor is in a field that is not within a scrolled area. 
2. No modifiable field follows the scrolled area. 


2.3.6.8 Illegal Terminator Interaction — If your program issues the ILTRM call 
with an argument of 1, any terminator that is illegal in its current context — 
for example, a Previous Field terminator in the first field of a form — is con- 
verted to a special terminator code, treated as if it came from the pressing of a 
function key, and sent to a function key UAR, if any. (See the description of 
the ILTRM case in Chapter 5.) 


The terminators that are affected are: NXT, ATB, PRV, XBK, XFW, SFW, and 
SBK. 


The first five of these are illegal if there is no next or previous field. The last 
four are illegal if the current field is not in a scrolled area. 


The illegal terminator symbols and values are: 


FDV$K_FT_ILG_NXT=11 
FDV$K_FT_ILG_PRV = 12 
FDV$K_FT_ILG_ATB =13 
FDV$K_FT_ILG_XBK = 14 
FDV$K_FT_ILG_XFW=15 
FDV$K_FT_ILG_SFW =16 
FDV$K_FT_ILG_SBK = 17 


2.3.7 Alternate Keypad Mode Terminators 


Normally, the numeric and punctuation keys on the VT100 and LK201 
keypads produce the same numbers and characters that the corresponding 
keyboard keys produce. Therefore, for many common applications, the opera- 
tor can enter numeric data by using the keypad rather than the keyboard. 


For special applications, you can set the VT100/VT200 to alternate keypad 
mode by issuing the SPADA call from your program or by enterng the DCL 
command | 


$ SET TERMINAL/APPLICATION. KEYPAD 


prior to running your application. You can then design the applications to use 
the numeric and punctuation keys on the keypad as field terminator keys. 
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The Form Driver then passes the alternate keypad mode terminators to the 
program immediately, regardless of whether the Response Required, Must 
Fill, and UAR requirements are satisfied for the form. 


Tables 2-6 and 2-7 include lists of the keypad keys that are affected by the 
alternate keypad setting and the code that is returned to your program for 
each key. Each character returned is the last character in the escape sequence 
generated by the key in alternate keypad mode. 


2.4 Key Functions and Key Codes 
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This section provides a fuller explanation of the roles of function keys, key 
functions, and key codes and gives their values. 
2.4.1 Form Driver Key Functions 


Form Driver key functions are actions the Form Driver takes in response to 
special keystroke sequences. Key functions, values for the DFKBD call, and 
default key sequences are given in Table 2-4. 


Table 2-4: Key Functions 


Function Default VT100 DFKBD 
Name Description Key sequence . Value 
FDV$K_KF_DLCHR Delete character DELETE 1 
FDV$K_KF_CRSRT Move cursor right Rightarrow 2 
FDV$K_KF_CRSLF Move cursor left Leftarrow 3 
FDV$K_KF_DLFLD Delete Field LINEFEED 4 
FDV$K_KF_INS Set Insert mode PF1 PF3 5 
FDV$K_KF_OVR Set Overstrike mode PF3 6 
FDV$K_KF_GOLD Start Gold sequence PF1 7 
FDV$K_KF_RESET Reset Gold sequence PF1 DELETE 8 
FDV$K_KF_RFRSH Refresh screen CTRL/AR 9 
FDV$K_KF_HELP Help PF2 10 
FDV$K_KF_NXT Next field TAB 11 
FDV$K_KF_PRV Previous field BACKSPACE 12 
FDV$K_KF_NTR Form or field complete RETURN 13 
ENTER 

FDV$K_KF_SBK Scroll backward Uparrow 14 
FDV$K_KF_SFW Scroll forward Downarrow 15 
FDV$K_KF_XBK Exit scroll area backward PF1 Uparrow 16 

' FDV$K_KF_XFW Exit scroll area forward PF1 Downarrow 17 


The first nine key functions are called the editing key functions; they are han- 
dled internally by the Form Driver and are not returned to your program. 
Interpretation of the other key functions is context dependent — they may be 
illegal, interpreted by the Form Driver, or returned to the calling program as 
terminators. 


Terminators are values returned to the calling program to indicate how input 
requests were completed. That is, terminators are key codes with a context. 
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Key functions in the proper context can give rise to a terminator code — not 
the same as the key function code. In addition, these key function terminators 
can be processed by the PFT call. Key codes that are not key functions are 
returned as terminators to the calling program. 


For the DFKBD call, FDV$K_KF_NONE is 0, and FDV$K_KF_DFLT is -1. 


2.4.2 Form Driver Key Codes 


Form Driver key codes are 16-bit encodings of certain key sequences. These 
‘sequences, listed in Table 2—5, are control characters, legal ANSI escape 
sequences, and 2-stroke sequences beginning with the Gold key. 


The definitions include the keystroke combinations interpreted by the Form 
Driver. Each combination has a coded value — an integer word — associated 
with it. The key codes are used in two ways. The most common is as the termi- 
nator to a field; the Form Driver returns terminators, and these are the codes 
for those terminators. The other way is to use these values as the key codes 
passed to the DFKBD call. 


All ASCII graphic characters are treated as data by the Form’Driver and are 
not available for use as terminators, except as the second key in a Gold 
sequence. The remaining keystroke combinations are divided into three 
groups as follows: 


1. Control keys, including the DELETE key 


2. Escape sequences, including keypad application mode keys, cursor posi- 
tion keys, and program function keys 


3. Gold sequences 


2.4.2.1 Control Keys — Control characters — ASCII codes 0 to 31(decimal) — 
and the DELETE key — ASCII code 127(decimal) are not allowed as data in 
fields. A control character not defined as a key function is returned to the call- 
ing program as a terminator. 


Control characters can be assigned to key functions, and several are assigned 
as defaults. The Form Driver key codes for control keys are listed in Table 
2-5. 


Note that the operating system may preempt the use of some control keys — 
for example, CTRL/Y. Using control keys other than those assigned as the 
defaults may lead to unexpected results. 


In Table 2—5, the first column contains the ASCII name for the control key, 
and the second column contains the ASCII value in decimal. Some of these 
codes — for example, CR — are produced by editing keys on the keyboard. 
Others are available only by holding down the CTRL key and pressing 
another key. 


The third column contains the name of the key the operator presses while 
holding down the CTRL key. The fourth column contains the Form Driver key 
code — the value to be used for the “defkbd” argument of the DFKBD call, or 
the value of the key as a terminator. 
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Note that the low-order byte of the key code is the 7-bit ASCII code for this 
key. For those keys used as part of the default Form Driver keyboard, the last 
column has the name of the associated key function. Some control keys have 
special meanings in terminals and cannot be used as terminators. This 
restriction is noted in the last column, although the absence of a note should 
not be taken as a guarantee that the key is available. 


Table 2-5: Key Codes for Control Characters 


ASCII Value Key Value Default 

Name (Decimal) CTRL/Key (as terminator) Assignment 
NUL 00 @ 1024+ 00 

SOH 01 A 1024+01 

STX 02 B 1024 +02 

ETX 03 °C 1024+ 03 

EOT 04 D 1024+ 04 

ENQ 05 E 1024 +05 

ACK 06 F 1024+06 

BEL 07 G 1024+07 

BS 08 H 1024+ 08 FDV$K_KF_PRV 
HT 09 I 1024+ 09 FDV$K_KF_NXT 
LF 10 J 1024+ 10 FDV$K_KF_DLFLD 
VT 11 K 1024+11 

FF 12 L 1024412 

CR 13 M 1024+13 FDV$K_KF_NTR 
SO 14 N 1024+14 

SI 15 O 1024+ 15 

DLE 16 P - 1024416 

DC1 17 Q 1024+17 

DC2 18 R 1024+18 FDV$K_KF_RFRSH 
DC3 19 Ss 1024+19 

DC4 20 T 1024+ 20 

NAK 21 U 1024+ 21 

SYN 22 V 1024+ 22 

ETB 23 Ww 1024+ 23 FDV$K_KF_RFRSH 
CAN 24 xX 1024+ 24 

EM . 25 a 1024 +25 

SUB 26 Z 1024+ 26 

ESC 27 [ Not available 

FS 28 \ 1024 + 28 

GS 29 ] 1024 +29 

RS 30 o 1024+30 

US 31 = 1024+31 


DEL 127 1024+127 FDV$K_KF_DLCHR 


2.4.2.2 Escape Sequences — The second group of keys consists of the cursor 
control keys, the program function keys, and the application keypad keys 
(Table 2-6). Note that the cursor control keys and program function keys 1 to 
3 are all assigned default Form Driver key functions. The key codes for the 
default editing functions are not returned to the program; instead, their func- 
tions are performed. For the terminator key functions, the context selected 
terminator code corresponding to the key function is returned. 


Form Characteristics | 


Table 2-6: Key Codes for Escape Sequences 


Default 
Key Code Value Name of Key Key Function 
FDV$K_AR_UP 99 Uparrow FDV$K_KF_SBK 
FDV$K_AR_DOWN _ 100 Downarrow FDV$K_KF_SFW 
FDV$K_AR_RIGHT 101 Rightarrow FDV$K_KF_CRSRT 
FDV$K_AR_LEFT 102 Leftarrow FDV$K_KF_CRSLF 


FDV$K_PF_1 103 VT100 PF1, VT52 Blue FDV$K_KF_GOLD 
FDV$K_PF_2 104 VT100 PF2, VT52 Red FDV$K_KF_HELP 
FDV$K_PF_3 105 VT100 PF3, VT52 Gray FDV$K_KF_OVR 
FDV$K_PF_4 106 VT100 PF4 
FDV$K_KP_NTR 107 Alternate keypad ENTER FDV$K_KF_NTR 
FDV$K_KP_COM 108 Alternate keypad , 
FDV$K_KP_HYP 109 Alternate keypad - 
FDV$K_KP_PER ~~ 110 Alternate keypad . 
FDV$K_KP_0O 112 Alternate keypad 0 
FDV$K_KP_1 113 Alternate keypad 1 
FDV$K_KP_2 114 Alternate keypad 2 
FDV$K_KP_3 115 Alternate keypad 3 
FDV$K_KP_4 116 Alternate keypad 4 
FDV$K_KP_5 117 Alternate keypad 5 
FDV$K_KP_6 118 Alternate keypad 6 — 
FDV$K_KP_7 119 Alternate keypad 7 
FDV$K_KP_8 120 Alternate keypad 8 
FDV$K_KP_9 121 Alternate keypad 9 
FDV$K_FK_E1 33 LK201 E1 
FDV$K_FK_E2 34 LK201 E2 
FDV$K_FK_E3 35 LK201 E3 
FDV$K_FK_E4 36 LK201 E4 
FDV$K_FK_E5 37 LK201 E5 
-FDV$K_FK_E6 38 LK201 E6 
FDV$K_FK_F6 49 LK201 F6 
FDV$K_FK_F7 50 LK201 F7 
FDV$K_FK_F8 51 LK201 F8 
FDV$K_FK_F9 52 LK201 F9 
FDV$K_FK_F10 53 LK201 F10 
FDV$K_FK_F11 55 LK201 F11 ; 
FDV$K_FK_F12 56 LK201 F12 FDV$K_KF_PRV 
FDV$K_FK_F13 57 LK201 F13 FDV$K_KF_DLFLD 
FDV$K_FK_F14 58 LK201 F14 
FDV$K_FK_HELP 60 LK201 HELP FDV$K_KF_HELP 
FDV$K_FK_DO 61 LK201 DO 
FDV$K_FK_F17 63 LK201 F17 
FDV$K_FK_F18 64 LK201 F18 
FDV$K_FK_F19 65 LK201 F19 
FDV$K_FK_F20 66 LK201 F20 


2.4.2.3 Gold Sequences — The last group consists of sequences starting with 
the Gold key. Any key not preempted by the terminal can follow the Gold key. 
Pressing a Gold key more than once is equivalent to pressing it once. The 
operator can cancel a Gold key sequence by entering the 
FDV$K_KF_RESET key function; that is, the sequence FDV$K_KF_GOLD 
FDV$K_KF_RESET is equivalent to the null sequence. 


The key or escape sequence following the Gold key determines the key code as 
listed in Table 2—7. The sequences expected to be used most often are given 
names. 
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Table 2-7: Key Codes for Gold Escape Sequences 


Default 
Key Code Value Key Sequence Key Function 

FDV$K_GAR_UP 227 Gold Uparrow FDV$K_KF_XBK 

FDV$K_GAR_DOWN 228 Gold Downarrow FDV$K_KF_XFW 

FDV$K_GAR_RIGHT 229 Gold Rightarrow 

FDV$K_GAR_LEFT 230 Gold Leftarrow 

FDV$K_GPF_1 231 Gold PF1 (VT100) _ FDV$K_KF_GOLD 
Gold Blue (VT52) 

FDV$K_GPF_2 232 Gold PF2 (VT100) FDV$K_KF_HELP 

Gold Red (VT52) 

FDV$K_GPF_3 233 Gold PF3 (VT100) FDV$K_KF_INS 
Gold Gray (VT52) 

FDV$K_GPF_4 234 Gold PF4 

FDV$K_GKP_NTR = 235 Gold Alt keypad ENTER 

FDV$K_GKP_COM = 236 © Gold Alt keypad , 

FDV$K_GKP_HYP 237 Gold Alt keypad - 

FDV$K_GKP_PER 238 Gold Alt keypad . 

FDV$K_GKP_0 240 Gold Alt keypad 0 

FDV$K_GKP_1 241 Gold Alt keypad 1 

FDV$K_GKP_2 242 Gold Alt keypad 2 

FDV$K_GKP_3 243 Gold Alt keypad 3 

FDV$K_GKP_4 244 Gold Alt keypad 4 

FDV$K_GKP_5 245 Gold Alt keypad 5 

FDV$K_GKP_6 246 Gold Alt keypad 6 

FDV$K_GKP_7 247 Gold Alt keypad 7 

FDV$K_GKP_8 248 Gold Alt keypad 8 

FDV$K_GKP_9 249 Gold Alt keypad 9 

FDV$K_GFK_E1 161 LK201 GOLD E1 

FDV$K_GFK_E2 162 LK201 GOLD E2 

FDV$K_GFK_E3 163 LK201 GOLD E3 

FDV$K_GFK_E4 164 LK201 GOLD E4 

FDV$K_GFK_E5 165 LK201 GOLD E5 

FDV$K_GFK_E6 166 LK201 GOLD E6 

FDV$K_GFK_F6 177 LK201 GOLD F6 

FDV$K_GFK_F7 178 LK201 GOLD F7 

FDV$K_GFK_F8 179 LK201 GOLD F8 

FDV$K_GFK_F9 180 LK201 GOLD F9 

FDV$K_GFK_F10 181 LK201 GOLD F10 

FDV$K_GFK_F11 183 LK201 GOLD F11 

FDV$K_GFK_F12 184 LK201 GOLD F12 

FDV$K_GFK_F13 185 LK201 GOLD F13 

FDV$K_GFK_F14 186 LK201 GOLD F14 

FDV$K_GFK_HELP 188 LK201 HELP FDV$K_KF_HELP 

FDV$K_GFK_DO 189 LK201 DO 

FDV$K_FK_F17 191 LK201 GOLD F17 

FDV$K_GFK_F18 192 LK201 GOLD F18 

FDV$K_GFK_F19 193 LK201 GOLD F19 


FDV$K_GFK_F20 194 LK201 GOLD F20 


Note that the value for a Gold escape sequence is 128 plus the value for the 
escape sequence. 


No symbols are defined for normal graphic or control keys preceded by the 
FDV$K_KF_GOLD key function because there are so many of them. Table 
2-8 gives the key codes for these key sequences. 
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Table 2-8: Key Codes for Gold Sequence 


ASCII Value 
(Decimal) 


Gold Key 


256 + 00 
256+ 01 
256 + 02 
256 + 03 
256 + 04 
256 + 05 
256 + 06 
256 + 07 
256+ 08 
256 + 09 
256 + 10 
256+ 11 
256 + 12 
256+ 13 
256 + 14 
256+ 15 
256 + 16 
256+ 17 
256 + 18 
256 + 19 
256 + 20 
256 + 21 
256 + 22 
256 + 23 
256 + 24 
256 + 25 
256 + 26 


256 + 28 
256 + 29 
256 + 30 
256+ 31 
256 + 32 
256 + 33 
256 + 34 
256 + 35 
256 + 36 
256 + 37 
256 + 38 
256 + 39 
256 + 40 
256 +41 
256 + 42 
256 + 43 
256 + 44 
256 + 45 
256 + 46 
256 + 47 
256 + 48 
256 + 49 
256 + 50 
256+ 51 
256 + 52 


Default 
Assignment 


Not available 


(Continued on next page) 
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ASCII Value 
(Decimal) 


Gold Key 


256 +53 
256 + 54 
256 + 55 
256 + 56 
256 +57 
256 + 58 
256+ 59 
256 + 60 
256+ 61 
256 + 62 
256 + 63 
256 + 64 
256 + 65 
256 + 66 
256 + 67 
256 + 68 
256 + 69 
256 +70 
256+71 
256+ 72 
256 +73 
256 +74 
256 + 75 
256 +76 
256+77 
256 +78 
256 +79 
256 + 80 
256+ 81 
256 + 82 
256 + 83 
256 + 84 
256 + 85 
256 + 86 
256 + 87 
256 + 88 
256 + 89 
256 +90 
256+ 91 
256 + 92 
256 +93 
256 + 94 
256 + 95 
256 + 96 
256+97 
256+ 98 
256 + 99 

256 + 100 

256+101 

256 + 102 

256+ 103 

256+ 104 

256 + 105 

256 + 106 

256 + 107 


Table 2-8: (Cont.) Key Codes for Gold Sequence 


Assignment 
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Table 2-8: (Cont.) Key Codes for Gold Sequence 


ASCII Value Default 
(Decimal) Gold Key Assignment 
108 256 + 108 
109 256 + 109 
110 256+ 110 
111 256+111 
112 256 + 112 
113 256+ 113 
114 256+114 
115 256 +115 
116 256+ 116 
117 256 +117 
118 256+ 118 
119 256+119 
120 256 + 120 
121 256+ 121 
122 256 + 122 
123 256 + 123 
124 256 + 124 
125 256 + 125 
126 256 + 126 
127 256+ 127 FDV$K_KF_RESET 
NOTE 


The key sequences listed below are reserved for future use by 
FMS. FMS may use them as default assignments in future ver- 
sions. If you use any of them now, you may have to alter your 
programs later. 


© Gold PF2 

e Gold TAB 

¢ Gold BACKSPACE 
e Gold CTRL/R 

e Gold CTRL/W 

e Gold LINEFEED 

e Gold RETURN 

e Gold Rightarrow 

e Gold Leftarrow 


In addition, on the LK201 terminal keyboard, the following 
key sequences are reserved for future use by FMS: 


e El 
e K2 
e K3 
e h4 
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e K5 

e K6 

e Gold El 

e Gold E2 

e Gold E3 

e Gold E4 

e Gold E5 

e Gold E6 

e Gold TAB 
e Gold F12 
eGoldF13 
e Gold HELP 


2.4.3 Defining Keys 


The following example shows how to use the DFKBD call to switch the func- 
tions of the RETURN and the TAB keys. After this call is executed, RETURN 
or numeric keypad ENTER will mean Next Field (FDV$K_FT_NXT), and 
TAB will mean Enter Form (FDV$K_FT_NTR). The example is given in 
FORTRAN. 

INTEGER TCA(3) 

INTEGER*#2 KEYTABLE(4) / FDV$K_KF_NTR» 

1033, 

1 FDV$K_KF_NXT» 1037 / 


CALL FDOVSATERM(ZDESCR(TCA) +1251) 
CALL FDVSDFKBD(ZDESCR(KEYTABLE) +2) 
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To improve the effectiveness of VAX FMS applications and to reduce the time 
required for you to produce fully debugged applications, the Form Driver 
maintains the completion status of each call and provides five ways for you to 
obtain the status: 


e Issuing the STAT call, which returns the Form Driver status code for the 
most recent call that was processed. The STAT call also returns the RMS 
system error code if a call fails because of an error in opening or reading a 
form library file or if other system problems are associated with terminal 
I/O. The status is returned as an integer longword as specified in an argu- 
ment of the call. 


e Issuing the SSRV call to establish either one or two global variables in your 
program to receive the FMS status after every FMS call. 
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e Issuing any call as a function returning a value. The returned status argu- 
ment conforms to the VMS calling standard. The status is returned as an 
integer longword. Each language has a different way of obtaining the VMS 
return status immediately from a call. For example, in FORTRAN, the sub- 
routine call is: 


CALL FDYSSTAT(USTAT sJSTAT2) 


The function value return call is: 
JSTAT=FDV$GET(FID»FVAL + TERM) 


e Using the Form Driver Debug mode for displaying explicit messages about 
the status of erroneous calls for added support while an FMS application is 
being developed. 


Using the VAX/VMS message facility with FMS. You can signal FMS 
errors from your program by using the standard VMS message facility. (See 
Table 2-9 for a list of the VAX FMS status returns.) You do this by using the 
LIB$SIGNAL call. See the Common Run Time Library Manual for a 
description of this call. 


When a VMS status is returned, it can be signaled as shown below: 


STATUS=FDV$LOPEN (’BADFILE’) 
CALL LIBSSIGNAL (ZVAL (STATUS)) 


Table 2—9 lists and describes the FMS status codes and the corresponding 
VMS status codes, which are global symbols. For FMS applications, the STAT 
call returns one of the listed numeric codes in the first of its two status 
arguments. | 


Two of the status conditions listed in Table 2—9 indicate an error in trying to 
open or read a form library file — code values FDV$_IOL and FDV$_IOR. In 
these two instances, the STAT call also returns, in the second status argu- 
ment RMS system error codes that help to define the exact cause of the prob- 
lem. For RMS errors, see the VAX/VMS System M essages and Recovery 
Procedures Manual. 


In addition, error code FDV$_SYS indicates that the Form Driver has 
encountered an unexpected error in dealing with the operating system — ter- 
minal services, usually. The RMS code can be accessed to find the error status 
returned to the Form Driver, which may identify the problem — for example, 
network link lost. 


Note that the status value FDV$_DLN — data specified too long for output — 
is reported only in Debug mode and is not returned to your program. Regard- 
less of Form Driver support for Debug mode, the specified data is truncated 
when displayed, and the Form Driver completes the call in the normal way. 
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VMS FMS 
Status Status 
Code Code 
FDV$_SUC 1 
FDV$_INC 2 
FDV$_MOD 3 
FDV$_IMP 2 
_FDV$_FSP -3 
FDV$_IOL —4 
FDV$_FLB -5§ 
FDV$_ICH —6 
FDV$_FCH -7 
FDV$_FRM -8 
FDV$_FNM -9 
FDV$_LIN -10 
FDV$_FLD -11 
FDV$_NOF —12 
FDV$_DSP -13 
FDV$_NSC -14 
FDV$_DNM - -15 
FDV$_DLN -16 
FDV$_UTR -17 
FDV$_IOR -18 
FDV$_IFN -19 
FDV$_ARG —20 
FDV$_INI —21 
FDV$_STR —22 
FDV$_IVM —23 
FDV$FVM -24 
FDV$_ITT —25- 
FDV$_TCA —26 
FDV$_STA —27 
FDV$_WID —28 
FDV$_NFL -29 
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Table 2-9: FMS and VMS Status Codes 


Meaning 


Successful completion of the call. 
Form is incomplete after a PFT call. 


Input successful. Field value in “fldval” has been modified by the 
operator. 


Length specified in “wksp” descriptor is not large enough. 


File specification in a LOPEN call was invalid. 


Form Driver encountered an error while reading the form library. 
(It reads the form library to verify that the file is a form library 
file.) 


Specified file was not a form library. 
Channel specified was either in use or invalid. 


Form was not resident, and when the Form Driver attempted to 
search for it in a form library, the current library channel was not 
open. 


Form description is invalid. 


Binary form description could not be found either in the form 
library, or in the list of memory-resident forms. 


Line or portion of form lies outside the visible screen range. 
Field doesn’t exist, or index value is invalid for field. 

Form contains no fields. 

Form contains only Display Only fields, or the specified field is 
Display Only. 

Field named is not a field in a scrolled area. 

No Named Data is associated with the specified name or index. 


Value argument supplied more data than was required, and some 
data was discarded. 


Field terminator code is invalid. 


I/O error occurred while Form Driver was reading in a form from 
the form library. The I/O error code is recorded in the current state. 
You can obtain it by issuing the STAT call. 


Field terminator code specified in the PFT call cannot be processed 
in the context indicated. 


Incorrect number of arguments for call. 
No workspace is defined. 
Value being returned is too large for the variable allocated for it. 


Not enough virtual memory could be allocated (either for the TCA 
or for the workspace). 


An error occurred in freeing virtual memory allocated to the 
application. 


Invalid terminal type. 
Terminal Control Area is invalid or undefined. 
Size of specified TCA is too small. 


Form being displayed does not fit on the screen (132-column form 
on a VT52). 


No form loaded into workspace. 


(Continued on next page) 


Table 2-9: (Cont.) FMS and VMS Status Codes 


VMS FMS 
Status Status 
Code Code Meaning 


FDV$_IBF 30 Area not large enough to hold the form. 

FDV$_NDS —31 Form is marked as being not displayed, so no input is possible. 
FDV$_UDP —33 UAR depth was exceeded. 

FDV$_UAR —34 UAR returned an illegal code. 

FDV$_UNF —35 UAR was specified, but not found. 

FDV$_CAN —39 Call was terminated by a CANCL call. 

FDV$_KIF 40 Illegal key function was specified in DFKBD. 

FDV$_KEX —41 Too many key codes were defined for some key function in DFKBD. 
FDV$_KT —42 Key code was given two key functions in DFKBD. 


FDV$_KIL —43 Illegal key code was given in DFKBD; that is, the key was not on 
the list in Chapter 2. 


FDV$_TMO —44 Operator took longer to respond than was allowed by the timeout 
value associated with the current terminal, for a GET-type call or 
WAIT call. 


FDV$_LLI —45 The Form Driver's internal buffer was not large enough to store 
the line image requested (in a RETFL call). The line image 
returned is truncated. 


FDV$_VAL —47 The value of an argument is outside the allowed range. 
FDV$_IFU —48 Illegal function while in currently active UAR. 
FDV$_SYS —49 Form Driver encountered system error response. 
FDV$_INA —50 Request information not available. 


2.5.1 Debug Mode Support for Application Program Development 


To use the Debug mode of the VAX Form Driver, you need to make the follow- 
ing logical assignment at DCL level: 


$ ASSIGN YES FDVS$DEBUG 


You can then run your application program without having to do any relink- 
ing. In Debug mode, the Form Driver reports explicit messages for status con- 
ditions of erroneous Form Driver calls. The Form Driver in Debug mode is 
useful during VAX/FMS program development. 


You can assign and deassign the FDV$DEBUG logical name during execu- 
tion of your program, since the Form Driver checks the the name upon each 
occurrence of an error. 


Once you have debugged the program, you should deassign the Form Driver 
Debug mode. When your program is running, the operators do not see the 
Debug mode messages provided explicitly for program debug. See Section 
2.5.2 for signaling the operator. 
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In Debug mode, the Form Driver signals you by ringing the terminal bell or 


reversing the screen video characteristics and displays a message on the bot- 
tom line of the screen for any of the error status conditions listed in Table 2—9. 
The Appendix in the VAX FMS Utilities Reference Manual lists the messages. 


After displaying a Debug mode message, the Form Driver places the cursor in 
the lower right corner of the screen until you press the ENTER or the 
RETURN key, regardless of how you may have redefined any keys. This pro- 


_cess prevents your program from clearing or overwriting a Debug mode mes- 


sage before you have seen it. When you press the ENTER or the RETURN 
key, the bottom line is cleared, and your program resumes. It can then issue 
the PUTL call to display program-related messages on the bottom screen 
line. 


The error code is returned to the calling program. 


Because the Form Driver explicitly signals all call errors when Debug mode 
is in effect, you can use the Form Driver to debug your FMS program. There- 
fore, after debugging a program, you may choose not to test for certain errors 
that should not occur in a fully debugged application — such errors as an 
incorrect field name or form name or an incorrect number of arguments in a 
call. The safest procedure is, of course, to check status after every Form 
Driver call. 


Even in a finished FMS program, you should check, at a minimum, I/O errors 
after calls that: 


@ Open and close a form library file 
e Display a form and must therefore read a form library file 


e Solicit operator responses 


NOTE 
FMS does not interact with the VAX/VMS Debugger. 


2.5.2 Signaling the Terminal Operator About Program Errors 


Your program can signal an operator about a problem by issuing the 
PUTL call. Here is an example of an I/O error being reported. The fol- 
lowing illustration shows one way you can use the PUTL call with the 
other status and error-checking features: 


1. The program encounters an I/O error while trying to display a 
form. 


2. The program detects the error by checking for a status of <0, using 
the STAT call. The call returns the error code —18 (FDV$_IOR) for 
an error in reading a form library file. 


3. The program uses the status code as an index into a list of program- 
specific messages. 


Form Characteristics 


4. The program issues the PUTL call to display the message on the 
bottom screen line and a SIGOP call to get the operator’s attention. 
The program then immediately issues the WAIT call to ensure that 
the message remains visible until the operator sees it and responds 
to it. 


The calls are described in full in Chapter 5. 


In BASIC: 


100 CALL FDV$CDISP (FORMNAME) 

110 CALL FDV$STAT (FMSSTATUS) 

200 IF FMSSTATUS < 0 

THEN 

CALL FDV$PUTL (‘FORM ’ + FORMNAME + ’ NOT FOUND’) 
CALL FDV$SIGOP 

CALL FDVSWAIT 


2.6 AST Considerations 


The FMS Form Driver is optionally AST reentrant, but you must follow cer- 
tain rules or risk severe problems, which the Form Driver cannot detect. 


1. You must not attach the terminal (ATERM) with No AST support (default 
is AST support). 


2. You can send output to the current form from an AST with no restrictions, 
although such output is more expensive in both time and characters sent 
to the screen. The reason for the added expense is that the Form Driver 
must always save and restore the video attributes and cursor position of 
the interrupted program. 


3. You must not request input from an AST program. 


4. You must not detach or switch a terminal or workspace or change a work- 
space involved in any current operation. 


There may be additional restrictions on the use of FMS from ASTs, depending 
on the version of the operating system in use. See the VAX FMS Installation 
Guide and Release Notes for details. 
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Chapter 3 
Programming Techniques and Examples 


Programming techniques are ways a programmer can exploit the capabilities 
of software inventively. In a new or greatly changed product, such ways are 
not likely to be immediately apparent to a new user. 


Typically, techniques evolve naturally through normal use — the user com- 
bines facilities in a certain way out of a need to accomplish a specific task, for 
example; or realizes that a facility meant to do one task is just the thing to 
solve some other kind of problem. 


Descriptions of such techniques make up this chapter, along with program- 
ming examples. The following routines, written in various languages, are 
taken from the FMS Version 2 Sample Application Program (SAMP). The 
routines illustrate the value of using such capabilities as Named Data and 
the various kinds of user action routines (UARs). Their value is in preserving 
as much as possible, the independence of the application program — that is, 
Named Data is associated with the form, and UARs are called from the Form 
Driver. 


3.1. Scrolling 


Because the Form Driver can store field values only for the fields that are on 
the terminal screen, your program must maintain all scrolled area field val- 
ues that are not displayed; that is, all the values that are “above” and “below” 
each scrolled area. When your program scrolls the lines of a scrolled area 
upward or downward, the program must collect the lines of values scrolled 
out of the area, and display any line of values scrolled into the area. (See the 
section called “Scrolling” in Chapter 2 for some discussion of this topic.) 


13000 
13001 
13005 
13010 
13015 
13030 
13035 
13040 
13072 
_ 13075 

13080 
13085 
13090 
13095 
13100 
13105 
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13115 
13120 
13125 
13130 
13135 
13140 
13145 
13150 
13155 
13160 
13165 
13170 
13171 
13175 
13180 
13185 
13190 
13192 
13195 
13200 
13205 
13210 
13215 
13220 
13225 
13235 
13245 
13250 
13255 


— 


3.1.1. Controlling Scrolied Areas 


DEF FN.VYUEREG 

[+ 

! Subroutine VYUEREG 

! View the check register and scroll through it. 

! Also display totals for current session. 

i 

! Put up register form, 

CALL FDV$CDISP( ‘REGIST’ ) _\ C=FN.SRVCHK 

1+ 

! Get number of lines in scroll area from form Named Data (item 1). 

1. 

NSCROLS = ‘ ‘’ ! Pre-extend string variable before call (BASIC only). 

CALL FDV$RETDI( 1%+ NSCROLS ) \ C=FN.SRYCHK 

NSCROL% = VAL( NSCROL# ) 

1+ 

! Put lines from check register array into scrolled area, 

! The window is initially from item 1 up to item 

! min(NSCROLS »+LASTREGNUMZ)» that is+ up to the size of the scrolled 

! area or the size of the registers whichever is less. Assume there 

! is at least one line (the initial deposit). 

te 

MINWINDOWZ = 1 

CALL FDOV$PUTSC( ‘NUMBER’»s REGARRAYS$(1) ) ! First Line 

CURLINEZ = 1 ! Reg item cursor is on 

WHILE ( CURLINEZ < LASTREGNUMZ AND CURLINEZ < NSCROLZ > 
CURLINEZ = CURLINEZ + 1 
CALL FDVSPFT( FDYVSK_FT_SFWs ‘NUMBER’ ) 
CALL FDVSPUTSC( ‘NUMBER’; REGARRAY$( CURLINEZ ) ) 

NEXT 

MAXWINDOWZ = CURLINE% 

+ 

! Get input from fake field of scrolled line and do what it saryss 

! Ked .». or RETURN/ENTER => return to menu 

! UPARROW or TAB => scroll forward 

! DOWNARROW or BACKSPACE => scroll backward 

! all others => ignore 

! Note that there is no form function Key UAR so this routine 

! handles all terminators itself (by ignoring illegal ones). 

. 

CALL FDVS$GET( FAKE$+ TERMINATORZ» ‘FAKE’ ) 

WHILE NOT (¢( TERMINATORZ = FOVSK_UFT_NTR OR TERMINATORZ = FDOVSKKP_PER ) 
IF TERMINATORZ = FDOVSK_FT_SFW OR TERMINATORZ FDOV$K_FT_SNX THEN C=FN.SCRF 
IF TERMINATOR? = FOVSK_FTUSBK OR TERMINATOR FDOV$K_FTUSPR THEN C=FN.SCRB 
CALL FDVS$GET( FAKE$+ TERMINATORZ:+ ‘FAKE’ ) 

NEXT 

FNEND 
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3.1.2 Scrolling Forward 
See also VUEREG routine at line 13000. 


13500 DEF FN.SCRFWD 
13501 I+ 
13505 ! Subroutine SCRFWD -- Scroll forward, 
13510 ! CURLINEZ is the line in the register that the cursor is on. 
13512 ! MINWINDOWZ and MAXWINDOWZ delimit the part of the register 
13513 ! currently displayed in the scrolled area 
13515 ! 
13520 
13525 I+ ; 
13530 ! If cursor is at the end of the registers reports and return 
13535 1. : 
13540 IF CURLINE% = LASTREGNUMZ THEN 

CALL FDV$PUTL( ‘Last line of register’ )} 

FNEXIT 
13545 1+ 
13550 ! If cursor not at the last line of a windows Just move down 
13555 ! If cursor is at the last line of a window» 
13560 “t move window forward one line» 
13565 ! write the new last line to the last line of the scrolled area 
13567 ! Move current line Pointer forward 
13570 1. 
13580 IF CURLINEZ <> MAXWINDOWZ THEN 

CALL FDVSPFT( FOVSK_LFTUSFW> ‘NUMBER’ ) 

ELSE 

MINWINDOWZ%Z = MINWINDOWZ + 1 

MAXWINDOWZ% = MAXWINDOWZ + 1 

CALL FDVUSPFT( FDVSK_FT_SFW, ‘NUMBER’s REGARRAYS( MAXWINDOWZ ) ) 
13585 CURLINEZ = CURLINEZ + 1 
13590 FNEND 
13698 

3.1.3 Scrolling Backward 
See also VUEREG routine at line 13000. 

13700 DEF FN.SCRBAK 
13701 I+ 
13705 { Subroutine SCRBAK -- Scroll backward 
13710 ! CURLINE% is the line in the resister that the cursor is on, 
13712 ! “MINWINDOWZ and MAXWINDOWZ delimit the Part of the register 
13713 ! currently displaved in the scrolled area 
13715 1. 
13720 
13725 1+ 
13730 ! If the cursor is at the beginning of the registers reports and return 
13735 !.. 
13740 _ IF CURLINEZ = 1 THEN ; 

CALL FDOVSPUTL( ‘First line of register’. ) 

FNEXIT 
13745 1+ 
13750 ! If cursor not at first line of the window; Just move up 
13755 ! If cursor is at first line of the window, 
13760. ! move window back one line» 
13765 ! write the new first line to the first line of the scrolled area 
13767 ! Move current line Pointer back 
13770 !. 
13780 IF CURLINEZ <> MINWINDOWZ THEN 

CALL FDOVSPFT( FOV$K_FT_SBK» ‘NUMBER’ ) 

ELSE 

MINWINDOWZ = MINWINDOWZ - 1 

MAXWINDOWZ = MAXWINDOWZ - 1 

CALL FDOV$PFT( FOVSK_FT_SBK+» ‘NUMBER’ » REGARRAYS( MINWINDOWZ ) ) 
13785 CURLINEZ = CURLINEZ - 1 
13790 FNEND. 
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3.2 Validating a One-Character Field — Using a UAR 


16010 
16015 
16017 
16020 


16025 . 


16030 
16035 
16040 
16045 
16050 
16055 
16060 
16065 
16070 
16075 
16080 
16085 


Purpose 


To check single-character fields for valid data input. 


Description 


Frequently when using forms as menus to select one of several options, a sin- 
gle-character field is used to enter a letter or number indicating the desired 
option. Although it is possible to have the application program test each of 
these fields separately to ensure that a valid choice has been entered, it is 
much more convenient to use a single UAR for this purpose. 


Whenever a character is typed in a single-character field, the character is 
immediately checked against a list of permissible characters, and the opera- 
tor is not allowed to proceed unless the character entered is found in the list. 


Programming Technique 


For you to use this technique for validating a single-character field, the asso- 
ciated data string of a field completion UAR must be set to contain a string of 
all the valid character responses. If space is a valid response, it must be 
embedded in the string, since trailing spaces are ignored. 


When the data validation UAR is activated, it uses the RETCX call (Return 
Current Context) to recover the associated data string, and the RETFN and 
RET calls to get the field name and field value, respectively. 


It then searches the associated data character string for the field value. Ifthe 
value is found, the UAR returns successfully, allowing a GETAL in progress 


to proceed normally to the next field. If the value is not found, the UAR 


returns validation failure, which causes the Form Driver to signal the opera- 
tor and stay in the current field. 


This technique is also used throughout the Form Editor for validating the 
selections for form and field attributes. 


Example 


+ 
VALID1 
UAR for field validation of any one character field. The 
UAR associated data has in it the legal characters allowed» © 
except that blank is not allowed unless it aprears before 
the first trailing blank. For example an assoc. value string 
‘aaqr’ implies that only the letters a» a» and r are allowed, 
A string ’ agar’ means that blank is accertable in addition 
to a» a+ and re Note that this routine is case sensitive 
(that is» it checks for correct case). ‘You can get around 
case sensitivity by using the force-uppercase field attribute, 
and Putting only capitals into the UAR associated value 
string. 


This routine can be used with any form and field since 
it determines the context for itself, 
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16088 I+ 

16089 ; DECLARE INTEGER CONSTANT & 
FOVSK_UVAL_SUC= 1000, !Field completion success & 
FOV$K_UVAL_FAIL=1001 !Field completion failure 


16090 | Pre-extend the strings into which FMS will return values 
16095 !. 
16096 FRMNAMS = SPACE$(31) 
16097 UARVALS = SPACE$(80) 
16098 FLDONAMES = SPACE$(31) 
16099 FVALUES = SPACE$(1) 
16105 
16110 t+ 
16120 ! Retrieve context: we will ignore TCA address» WKSP address» FRMNAM$> 
16125 ! CURPOS» FLDTRMs INSOVR» and HELPNUM using only UARVAL$» and 
16127 ! only the initial» non-blank characters of it. 
16130 ! Retrieve field name and index, 
16135 ! Retrieve field value. ' 
16140 CALL FDVSRETCX( TCAZ»s WKSPZ+ FRMNAM$+ UARVAL$» CURPOSZ,» FLDTRMZ+ INSOVRZ+ HELPNUMZ ) 
16142 UARVALS = TRM#( UARVALS ) 
16145 CALL FDV$RETFN( FLDNAMES, FINDEX2Z ) 
16150 CALL FDV$RET( FVALUES>» FLDNAME$» FINDEX% ) 
16160 
16165 1+ 
16170 ! To be valid» FVALUES must occur in the string UARVALS 
16175 t- 
16185 IF POS( UARVALS+ FVALUE$, 1) > O THEN 

VALID1 = FOV$K_UVAL_SUC !Success 

ELSE 

CALL FDVSPUTL( ‘Illegal value’ ) 

VALID1 = FDV$K_UVAL_FAIL 
16210 FUNCTIONEND 


3.3. Producing Hard Copy — Using Named Data 


Purpose 


To produce a printable image of a form or portion of a form. 


Description 


A common application requirement is to produce a printable copy of a form on 
the screen. Complications arise if only part of the form is to be printed or if 
only one form out of a set of multiple forms on the screen is to be printed. The 
program could select particular lines to be printed, but doing so would destroy 
some of the program/form independence that is one of the chief virtues of 
FMS. Changes to the layout of a form might then require the program to be 
changed when the changes would be only cosmetic and should not be affecting 
the program. 


Programming Technique 


The RETFL call returns the printable image of an individual line on the 
screen. These line images are suitable for writing directly to a line printer or 
to a file for later printing. If the entire screen is to be printed, a program loop 
requesting lines one through twenty-three will produce the twenty-three line 
images. 


When only part of the screen is required, the difficulty is in knowing which 
lines to ask for in the RETFL call. A common technique is to store the range of 
the lines to be printed with the form itself. At form creation time the form 
designer knows what lines are to be printed and puts the numbers of the first 
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and last lines to be printed in the form’s Named Data. The program accesses 
the Named Data to find the first and last lines to print and uses them as limits 
on the program loop calling RETFL. Then, if the form layout is ever changed 
so that a different range of lines should be printed, the form designer changes 
the Named Data and the unchanged program still produces the desired 
result. 


Example 


The following extract from the FMS Sample Application program shows this 
technique in action. The form has two Named Data items with names FIRST 
and LAST indicating the first and last lines to print. Each item has two char- 
acters representing the number. The program reads those Named Data items, 
which are character strings, converts them to numbers for internal use, and 
uses them as limits on a loop that includes a call on RETFL and a statement 
that writes the line images to a data file. 


The following segment is shown in FORTRAN. See the VAX FMS Language 
Interface Manual for the equivalent code segment for any other languages 
supported by FMS. That manual also has descriptions of the CHECK form. 


SUBROUTINE PRINT THE CHECK 
Print the check into the file SAMPCH.DAT 
CHARACTER#80 LINE 
CHARACTER*#2 FIRSTL >» 
1 LASTL 


INTEGER FIRST _LINE_NUMBER » 


1 LAST.LINE NUMBER » 
2 I> 
3 LINELENGTH 


Oren check writing file. Note there’s a new version 
for every check. 


OPENCUNIT=2, FILE=’SAMPCH.DAT’+» STATUS=’NEW’ » 
1 CARRIAGECONTROL=’LIST’»s RECORDSIZE=80 ) 


Get the top and bottom lines of the check from the named data 
(first two characters), 


CALL FDOV$RETDN( ’FIRST’»s FIRSTL ) 
CALL CHECK _FMSSTATUS( ) 

CALL FDOVSRETDN( ‘LAST’,s LASTL ) 
CALL CHECK FMSSTATUS( ) 


Get lines from form. 
Write to file. 


READ (FIRSTL» ‘(12)’) FIRST -LINE_-NUMBER 
READ (LASTL» ‘(12)’) LAST.LINE NUMBER 


DO I = FIRST_LINE_NUMBER» LAST -LINE.NUMBER 
CALL FDOV$RETFL( I+ LINE» LINELENGTH ) 
WRITE(2+’(A)') LINEC1:LINELENGTH) 

ENDDO 

CALL FDVS$PUTL( ‘Check written to file’ ) 

CLOSE (2) 

END 
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3.4 Storing Message Text — Using Named Data 


Purpose 


Keep operator message texts independent of your program. 


Description 


Messages to the terminal operator are often changed during development of 
an application. To keep the messages independent of the peculiarities of a 
particular programming language, you can use files and modules that con- 
tain only message text. 


When a form changes, it is often necessary to change the message file also. 
Even after program development, convenient change of operator messages is 
desirable. A program product may need to change both forms and message 
files to be tailored for a new customer. A program that is used by operators 
who speak different languages must maintain different form and message 
files for each language. 


Programming Technique 


One way of simplifying control of operator interaction is to keep all text that 
is presented to an operator in an FMS form. In the case of a multilingual envi- 
ronment, the application designer can develop forms that all request the 
same information, but that have background text appropriate to the lan- 
guage (for example, German and French). 


All forms for a single language are collected in a form library. There may be 
several such libraries, each containing forms having identical names, with 
the only difference being the background text. The first form that the applica- 
tion displays is a menu form requesting the operator to select a language. The 
application opens the appropriate form library according to the language 
selected. 


Thereafter, when a form is called from the library (for example, with a CDISP 
call), the named form is read from the library and displayed on the screen, 
presenting text in the operator’s language. The application doesn’t need to be 
concerned with the language at that point, since the previously made choice 
controls the form displayed now. 


Since the application must occasionally display additional messages (per- 
haps by means of the PUTL call to the bottom line of the screen), it is consis- 
tent to store the text of those messages in the Named Data of the form. Either 
the name or index of the Named Data item can be used as an identifier to 
retrieve the text from the form before sending it to the operator. 
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In the multilingual environment, these messages can be in the selected lan- 
guage. Even for single language environments, storing the message with the 
form makes sense, since the messages often relate to the form. The form 
designer can change the form and the related messages in the same place, 
saving time and the usual confusion when separate files must be used 
together. 


Example 


The Sample Application shows one example of how to use Named Data to 
store message text in the DEPOSIT form. After the operator has entered 
checking account deposit information, SAMP wishes to display a message to 
the effect that the operation is done and the operator should press the 
RETURN key to continue. The form used for deposit entry has such a mes- 
sage stored in the Named Data item with the name DONE. 


The following extract from the FORTRAN SAMP shows how this can be done. 
Consult the VAX FMS Language Interface Manual to see the form definition 
for DEPOSIT and the SAMP in any of several languages. 


CHARACTER*80 DONE- 


CALL FDVSRETDN( ‘DONE’,» DONE ) 
CALL FOVSPUTL( DONE ) 
CALL FDVSWAIT 


3.5 Converting Function Keys to Field Entry 


Purpose 


Provide an easy way of accepting either function keys or text in a field to 
select an option from a menu. 


Description 


In menu entry forms it is often desirable to allow the operator to enter the 
choice in one of two ways: enter the option followed by a terminator, or enter a 
function key. It is often inconvenient to implement such a design, since it 
involves two sets of validations instead of just one (making sure the text is 
correct, or if that is blank, making sure the function key is correct). Nonethe- 
less, the convenience of a single keystroke menu response makes it worth 
considering. 


Programming Technique 


A function key UAR can convert a function key to the text string it is 
equivalent to. The UAR then outputs that text string to the menu’s choice 
field as if the operator had entered the text. The return code for the UAR tells 
the Form Driver to process the field as if the operator had pressed the 
RETURN key instead of a function key. The Form Driver then calls any field 
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completion UARs or returns control directly to the calling program, which 
only has to look at the text, regardless of whether it has been entered from the 
keyboard or by means of a function key. 


Example 


The Sample Application’s MENU form has a function key UAR that converts 
six function keys into the text strings “1”, “2”, “3”, “4”, or “5”. The function 
keys accepted are all on the application keypad. The key 1 and the key period 
(.) are both converted to the string “1”; the key 2 is converted to the string “2”; 
keys 3, 4, and 5 are converted to strings “3”, “4”, and “5”. All other function 
keys are rejected. While this is a specific UAR, more general UARs to do this 
conversion can be written. 


The following extract from the COBOL SAMP shows how this can be done. 
Consult the VAX FMS Language Interface Manual to see the form definition 
for DEPOSIT and the SAMP in any of several languages. 


IDENTIFICATION DIVISION. 

PROGRAM-ID,. TAKE1I5 INITIAL. 

HH KEKE KKH HEHEHE KEKE KEK HEHEHE EE HEHE EEE HEHE EE EEE HEE EERE EEE REE ERE ER EEHRES 
* Function Key User Action Routine for the MENU form of SAMP.+* 


* Convert Kerpad 1-5 into field values 1-5. * 
¥ Convert Keypad period into field value l. ¥ 
* Reject all other function Keys with error message, * 


HH KHER HEHEHE EEE KEE HEHE EEE EEE EEE KEKE EEE EER EER EE EEE EERE REE EE REESE 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
COPY "FDVDEF", 
COPY "SAMPCOB",. 
COPY "SMPCOBUAR". 
¥ 
* Declarations specific to this UAR. 
¥ 


01 FIELD_VALUE PIC X(1) VALUE SPACE. 
01 ILLEGAL_FUNC_KEY_MSG PIC X(20) 
VALUE "Tllegal function Key". 
PROCEDURE DIVISION GIVING RETURN_STATUS. 
0. 


+ 
* Retrieve context: ignore all but TERMINATOR 
to 
CALL "FDV$RETCX" USING BY REFERENCE ADDRESS_TCA, 
BY REFERENCE ADDRESS_WKSP; 
BY DESCRIPTOR FORM NAME» 
BY DESCRIPTOR UAR_DATA, 
BY REFERENCE CURSOR_POSITION;, 
BY REFERENCE TERMINATOR: 
BY REFERENCE INSOVR_STATUS» 
BY REFERENCE HELP STRIKES. 
+ 
* Do the conversion, displaying the value converted if found, 
* ReJect if not one of the expected terminators. 
%— 
EVALUATE TERMINATOR 
WHEN FDV$K_KP_1 MOVE "1" TO FIELD VALUE 
WHEN FDOV$K.-KP_2 MOVE "2" TO FIELD VALUE 
WHEN FOV$K_KP_.3 MOVE "3" TO FIELD VALUE 
WHEN FOV$K_KP_4 MOVE "4" TO FIELD_VALUE 
WHEN FDV$K-KP_5S MOVE "5S" TO FIELD_VALUE 
WHEN FDV$K_KP_PER MOVE "i" TO FIELD VALUE 
END-EVALUATE. 
IF FIELD.VALUE = SPACE THEN 
CALL “FDOV$PUTL” USING 
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BY DESCRIPTOR ILLEGAL._FUNC_KEY_MSG 
CALL "“FDV$SIGOP" © 


% Just ignore it now. 
MOVE FDOVSK_UKEY_SUC TO RETURNUSTATUS 
ELSE 


CALL "FDV#PUT" USING BY DESCRIPTOR FIELD VALUE 
BY DESCRIPTOR N-MENU-OPTION 


* Treat as if it is RETURN, 
MOVE. FOVSK_UKEY_NTR TO RETURN STATUS 
END-IF. 


EXIT PROGRAM. 
END PROGRAM TAKE1S,. 


3.6 Filter for Function Keys 


Purpose 


Allow only certain function keys to be returned to the program. | 


Description 


FMS defines a great many function keys (control keys, Gold sequences, termi- 
nal function keys, alternate keypad keys), but most applications only need a 
few keys active during the processing of a particular form. Other keys can be 
rejected or ignored. On return from a GET-type call the application can deter- 
mine whether the terminator is legal, but this is such a common requirement 
that a general purpose routine can save a lot of trouble. 


Programming Technique 


Define a general purpose function key UAR for the form, that allows only cer- 
tain function keys to be returned to the program. One way of doing this is to 
have the UAR associated data be a string that has the keycodes of the legal 
function keys. 


The form designer then specifies the UAR in the Form Phase of the Form 
Editor or in the FORM statement of the Form Language, with an associated 
data value representing just those function keys that are legal. (About 
twenty keys could be specified in this fashion, more than an operator can usu- 
ally deal with.) The function key UAR reads the associated data string and 
compares the values found there to the keycode received, rejecting the key if 
no match is found. 


Alternatively, if you want to change the legal function keys more often than 
you switch the form, or if you wish to have more keys than can be listed in the 
eighty bytes of the UAR data, define a COMMON area with an array contain- 
ing the legal keycodes, and a variable specifying how many different 
keycodes are currently in the array. 


The application program updates the array and the counter variable when- 
ever it determines that a different set of functions is legal. A function key 
UAR can access the array in COMMON, comparing the key code received 
against the legal values, and returning success to the Form Driver only if a 
match is found. 
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Example 


The Sample Application has a function key UAR called PASSKY that is used 
on each of the data entry forms in SAMP. PASSKY implements the first of the 
suggestions above — the UAR associated data string has the legal keycode 
values. PASSKY is given below in its PASCAL version. Consult the VAX 
FMS Language Interface Manual to find PASSKY in any of several lan- 
guages. You can also find references to the SAMP forms that use PASSKY. 


(It is possible to write a more efficient implementation of PASSKY than is 
shown here. Instead of converting each of the character strings in the UAR 
data string to binary and then comparing the binary number to the termina- 
tor, you can convert the terminator to a four character ASCII string (with 
leading zeros) and then use a string function to see if it appears in the VAR 
data string. Each string in the UAR data would have to be four characters 
long, with leading zeros, for this to work.) 


FUNCTION PASSKY3 


{ General function Key uar to Pass only those from the (small) 
list in the uar associated value string and reJjJect all 
others. The list is of the forms 

nm toneblank? n <oneblank? 4+ mn <¢manyblanks> 
For example the string ‘110 112’ would accept Keyvpad period 
and Keypad zero but no other function Keys. } 


LABEL 10005 

VAR Nexttrm: INTEGERS 
NonBlank: INTEGER: 
NextBlank: INTEGERS 


BEGIN 


{ Retrieve context: we will ignore TCA address+ WKSP address; 
FRMNAMs INSOVR» and CURPOS»s using only FLOTRM and 
UARVAL. } 


A := Teas WKSP : 
Uarvals CURPOS 
Insours HLPNUM 


Workspaces FRMNAM := Franams 
Curpos» FLDTRM := Fldtrm;, 
H 


lenum )3 


UARVAL 
INSOVR 


peo 


FOV$RETCX( T 


{ Break up the list into numbers. Check each against the 
terminator. If terminator found in lists return success. } 


Nonblank := 13 { Beginning of string} 
WHILE (UarvalCNonblank] <> ‘ ’) AND (Nonblank <= 80) DO 
BEGIN 


Nextblank := INDEX( SUBSTR(Uarval,+s Nonblank» 
LENGTH(Uarval) - Nonblank + 1)» % “%) 

IF Nextblank = 9 

THEN Nextblank := 80 

ELSE Nextblank := Nextblank + Nonblank - 13 

READY (SUBSTR(Uarval,s Nonblank»s Nextblank-Nonblank) » 
Nexttrm) 5 

IF Fldtrm = Nexttrimn 


THEN 
BEGIN 
PASSKY := FDV$K_UKEY_TRM§ {Pass Key to application} 
GOTO 10003 
END; 
Nonblank := Nextblank + 15 
END; 


PASSKY := FDV$K_UKEY_ERR3 {Let FDV do the beeping} 
1000: END$ 
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3.7 Range Checks for Fields 
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Purpose 


Ensure that a field contains values only in a particular range. 


Description 


Many fields can contain numeric values only in certain ranges, which are 
known ahead of time and which do not need to change dynamically. For exam- 
ple, there may be a minimum order on certain items, or only certain tempera- 
ture ranges may be possible in a laboratory environment. While it is possible 
to check these values in the application, it is more convenient to define a gen- 
eral purpose field completion UAR. 


UARs are particularly useful because the main logic of the application pro- 
gram does not then have to concern itself with validity checks of this sort. The 
validity checks still have to be made, but they are made in a modular fashion 
in a subroutine that does not clutter up the main line, and that is usually 
more concerned with relationships between the entered data and a database 
or realtime process. 


Programming Technique 


A range checking UAR can be specified for each field that requires range 
checking. The lower and upper bounds for the field values are specified in the 
UAR associated data, separated by a comma. If no lower or upper bound is 
given, then no check for the bound is made, allowing ranges with open bounds 
on one end. The UAR data can also contain an error message to be issued in 
case of failure to satisfy the validity check. 


Just putting a UAR on a field doesn’t always mean that the UAR is called. 
There are two conditions (other than error conditions, cancellation of the call, 
and field timeout) under which the Form Driver does not call a UAR for a field 
— the field was terminated by the Previous Field key, or the field was termi- 
nated by a user function key. 


In either of these situations the program must realize that the field may have 
invalid data. The program can take steps to guarantee that the UARs for the 
field get called so that its validity is assured. The program may refuse to 
accept such a terminator, and reestablish the read on the field or the form as a 
whole. 


The program may call the PFT routine with the Enter Form terminator 
(FDV$K_FT_NTR). The Form Driver then checks all nonscrolled fields for 
validity, calling their UARs and returning a special status code to the pro- 
gram if any field fails to pass all checks. The program can reissue the read for 
the failed field and continue until the PFT routine returns success. 
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Example 


The Sample Application program has a function, RANGE, that is called asa 
field completion UAR. The BASIC version of RANGE is given below. Consult 
the VAX FMS Language Interface Manual for examples of RANGE in other 
languages. Refer to the CHECK form in that manual for the field that uses 
this UAR. 


Note that RANGE is not completely robust with respect to the UAR associ- 
ated data string. A string that contains illegal numeric values on either side 
of the comma will cause problems. If your program is debugged, RANGE 
causes no problems, but a more general function would have to have some 
method of either checking for valid numbers, or a method of recovering from 
errors. The RANGE function in SAMP is used for integer values. Some of the 
language implementations actually allow decimal numbers because of the 
particular conversion functions used (for example, BASIC). 


You can make RANGE more efficient if you require that the numbers in the 
UAR string be fixed format instead of free format. For example, the lower 
bound might occupy string positions 1-10; the upper bound, positions 11—20; 
and the error message, positions 21-80. The advantage for RANGE is in not 
having to scan for the numbers. The disadvantage, of course, would be for the 
form designer — fixed format input is inconvenient and subject to error. 


FUNCTION INTEGER RANGE 
LEH KEKE EEK EK ERE EERE RHEE HEE EEE KEKE EEE EE EEE EEE EE REE EERE REE EERE EERE EERE 
! General purpose UAR to check the range of any numeric item. The 
associated UAR data must have one of the four forms: 

L;U<space?{message} 

+U<space>{message} 

Lit space+{message} 

*isPace {message} 
where L is lower bound: WU is upper bounds and {message} is an 
oPtional error message in case the field value is out of bounds. 
If one of the bounds isn’t givens it isn’t checked for. If neither 
bound is givens nothing is checked» everything succeeds. If the 
UAR. value doesn’t have a commas a FDV$_UAR error message is returned 
to the calling program by the FOV so the form designer has to go 
back and do it right. If no {messagdge} is given» a simple 
"out of range Usk" message is given to the hapless operator, 


This VAR can work with any form and numeric field since it gets 
context itself. Care must be taken with fields using field marker 

! periods since those periods are not returned to the Program. 

LEHR HHH HEHEHE EEE EEE EE KEE EHH EEK HEHEHE HEHEHE EH KH HEHEHE HEHEHE KEE EE HEEEEEES 


ee a ee ery 


DECLARE INTEGER CONSTANT & 
FOV$K_UVAL_SUC= 1000, !Field completion success & 
FOVSK _UVALUFAIL=1001 'Field completion failure 


I+ 

! Pre-extend the strings into which FMS will return values, 

1 Get context which yields associated data value (ignore other stuff). 

! Get current field name and index. 

! Get field value. 

1- 

FRMNAMS SPACE$(31) 

UARVALS SPACE$(80) 

NAMES = SPACE#$(31) 

NUMBERS = SPACE$#(132) 

CALL FDV$RETCX( TCAX+ WKSP%Z»+ FRMNAMS+ UARYALSs CURPOSZ+s FLDTRMZ> & 
INSOVRZ» HELPNUMZ ) 

CALL FDVSRETFN( NAMES+s INDEX” ) 

CALL FDOV$RET( NUMBERS» NAMES, INDEX% ) 

NUMBER = VAL( NUMBERS ) 

1+ 

! Find comma and blank delimiters. 


non 
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! Check for lower bound. 
Vis 
COMMAZ = POS( UARVALS, ‘+’ » 1 ) 
BLANKZ = POS( UARVALS,+ SPACE$(1)+ COMMAZ + 1 ) 
IF COMMAZ = O THEN 
RANGE = 0 ! Tllegal UARVAL string» FOV returns error 
FUNCTIONEXIT 
IF COMMAZ <> 1 THEN 
IF NUMBER < VAL( SEG$( UARVALS,s 1+ COMMAZ - 1 ) ) THEN 20300 
1+ 
! Check for upper bound 
Is 
IF BLANKZ <> COMMA% + 1 THEN 
IF NUMBER > VAL( SEG$( UARVALS,» COMMAZ + 1+ BLANKZ - 1 ) ) THEN 20300 
i+ 
! Passed both tests successfully» return success for UAR value 
! 
RANGE = FDV$KUUVAL_ SUC 
FUNCTIONEXIT 
1+ 
! Error in one of the bounds, 
! Give error message: either from the UARVAL or make one uP, 
1. ; 
IF SEG#$( UARVALS; BLANK% + 1+ BLANKZ + 1 ) <3 SPACE$(1) THEN 
CALL FDV#$PUTL( SEG$( UARVALS,» BLANKZ + 1+ 80 ) ) 
ELSE 
CALL FDV#PUTL( ‘Field value out of bounds. Must be in range "’ + & 
SEG$( UARVALS, 1+ BLANKZ - 1) + ‘",% ) 
CALL FDVS$SIGOP [Beers too, 
RANGE = FDOVSK UVAL_FAIL 
FUNCTIONEND 
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Purpose 


General purpose structure for getting input from all fields in a form. 


Description 


One of the advantages of the GETAL call is that it allows the operator to pro- 
gress through the form with the Next Field and Previous Field keys, filling in 
fields in any order (subject to Response Required and Must Fill attributes, 
and UAR validations). Only when the operator presses a function key or the 
Enter Form key does the Form Driver return control to the application; and if 
the Enter Form key is pressed, the Form Driver does not return control if any 
field fails validation. 


Even though a program requires input from each input field on a form, there 
are many situations in which the GETAL call is inappropriate. GETAL does 
not access scrolled fields, and in some cases the mainline program needs to 
regain control after each field is entered. 


The restriction on no scrolled fields is put on GETAL because the program 
must know at all times what the current scrolled line is in a scrolled area. If 
GETAL were to accept input from scrolled lines, and were to allow the user to 
scroll down, the program’s knowledge of the current scrolled line would not 
match the Form Driver’s knowledge. The reason for this mismatch is that 
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there is no way in FMS for the Form Driver to tell the application the number 
of the current scrolled line, and no way to inform the application if the whole 
area is to be scrolled. 


The only way the current scrolled line is changed is by the application’s 
requesting a change (by means of the PFT call with the SFW, SBK, SNX, and 
SPR terminators; or by means of PUTDA ’s restoring the current scrolled 
lines of all areas to one). Since the application controls scrolling it can always 
know the current line. 


A mainline program might wish to regain control after every field to achieve 
special effects. These effects might not be appropriate for UAR processing for 
a variety of reasons. The restrictions on UAR processing may be too severe for 
the effect. For example, the effect might be to skip over some field if some 
other field has a particular value, but a UAR cannot change the current field; 
or, the language being used does not support external routines. 


Although these are good reasons not to call GETAL, it is not advisable to give 
up the operator’s apparent freedom of order entry afforded by GETAL. 


Programming Technique 


It is possible to give the operator the same apparent freedom of control and 
still have control return to the application for every field. The general idea is: 


1. Perform a GET for the first (or any other field). 


2. Do the special processing for the named field after control returns to the 
program. 


3. If the terminator specifies scrolling and you are in a scrolled area, update 
your data pointers for that scrolled area. (The Form Driver does not nor- 
mally return scrolling terminators if the field is not in a scrolled area.) 


4. Call PFT, specifying the field name used in the GET, and the terminator 
that was returned by GET. Ask that the new current field name be 
returned by PFT. This step requests that the action expected by the opera- 
tor be carried out, at least in the internal memory of the computer (chang- 
ing the current field). Note that neither the cursor nor the screen changes 
because of the PFT call. 
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5. Inspect the return from the PFT call. It can be one of four values: 


e FDV$_SUC: Success; the field name returned by PFT is the new current 
field name. If the terminator was not FDV$K_FT_NTR, your program can 
continue asking for input using the field name returned. If the terminator 
was FDV$K_FT_NTR, then the input is finished. 


e FDV$_INC: The field terminator was FDV$_FT_NTR and some field 
did not pass all the validation criteria. The current field is set to the first 
such field and is returned to your program. Your program can continue 
asking for input using the field name returned. 


e FDV$_UTR: The field terminator was a function key and not a termina- 
tor known to FMS. The current field is not changed and its name is 
returned to your program. You then choose what your program does 
depending on the function key. You may choose to continue input from the 
current field, which was returned to you. 


e FDV$_IFN: The terminator requests an illegal function in the current 
context (for example, Next Field at the end of the form). The only way this 
can be returned is if you have changed Supervisor Only mode since the 
GET statement. The GET call does not return a terminator that is illegal 
in the current context, so it must be that the context has changed. 


For example, at the time of the GET call, Supervisor Only mode was off 
and there was a Supervisor Only field following the current field, making 
the Next Field terminator legal. If you turn on Supervisor Only mode and 
there are only Supervisor Only fields following the current field, the Next 
Field terminator is now illegal. If you change the context you must decide 
what to do next. (Note that turning on Supervisor Only mode may also 
change the validity of the current field, since it may no longer be a modifia- 
ble field.) 


-6. Note that for the first three (normal) cases, your program may elect to con- 
tinue input with the field that was returned to you by the PFT call. Your 
program can loop back to use that field name in the next GET call. Using 
the new current field name in the GET call makes it appear to the operator 
as if the cursor has moved in response to the terminator entered, which it 
indeed has, but only after the program has requested such movement. 


When the FDV$_FT_NTR terminator is entered and PFT returns success for 
it, your program knows that all the nonscrolled fields have been entered cor- 
rectly. You can be assured that all scrolled fields that were entered with any 
terminator other than FDV$_FT_PRV, FDV$_FT_SPR, or a function key 
are correct. That is, the scrolled line fields were validated up to the farthest 
point on the line reached. 


Note that this technique works for any form since it does not need to know the 
field names. Of course, if you wish to do special processing for particular 
fields, you need the field names. 


Programming Techniques and Examples 


Example 


The following code is extracted (in slightly modified form) from the Sample 
Application. The technique is used in SAMP only for illustrative purposes 
(there is no special processing done for a field). The difference between the 
SAMP code and that given here is that the SAMP code does a GETAF for most 
of the fields so that it regains control only after a field changes (except the 
first). The code listed below regains control after every field. Depending on 
the needs of your program, you may choose to do one or the other. The code 
below also differs from the SAMP in the way the call status is obtained after 
the PFT call. | 


The code segment below is for PL/I. Consult the VAX FMS Language 
Interface Manual for the SAMP program using GETAF in your favorite 
language. 


SIMULATE: PROCEDURE 

DCL FIELDNAME CHAR(31)+ /*Name of field#/ 
FIELDINDEX FIXED BIN(31),» /*#Index of field*/ 
FIELDVALUE CHAR(80)5 /#Value of field*/ 


FIELDNAME = ‘735 /* Identifies first field in form */ 
DO WHILE ('’1°B)5 
CALL FDV$GET( FIELDVALUE+ TERMINATOR+ FIELDNAME; 
FIELDINDEX ) 


/* 

/* Do any special processing for field FIELDNAME here, 
4® vase ; 

/* Go to next or Previous field or leave form 

/% */ 

CALL FDVSPFT( TERMINATOR: + » FIELDNAME,s FIELDINDEX )3 
/* , 


/* If status is errors then PFT failed because terminator 
/* was a Keypad Keys which means return to caller, 
/* *¥/ 
CALL FDVSSTAT( FMSSTATUS )35 
IF FMSSTATUS < 0 THEN RETURN: 
IF TERMINATOR = FOV$K_FT_NTR 
THEN IF FMSSTATUS *= 2 
THEN RETURNS 
ELSE DO3 
CALL FDVS$PUTL( ‘INPUT REQUIRED’ )35 
CALL FDV$BELL35 
END$ 
/* Loops using new field name */ 
END 3 
END SIMULATE 3 
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3.9 Reducing Display Times for Forms 


Purpose 


Reduce the time to display a form and application supplied data. 


Description 


It is often the case that you will display a form (for example, with DISP) and 
then immediately output data to all the form’s fields. This results in the fields 
on the forms being written twice — once as the result of the DISP call output- 
ting the default values, and once as the result of PUT calls or the PUTAL call. 
On a form with many fields this is a noticeable delay, especially on low-speed 
lines, and is distracting. 


Programming Technique 


Instead of using a DISP call to load the form into a workspace and display the 
form, and then using PUT calls, perform the following sequence: 


1. Load the form into the workspace with LOAD (which does not display the 
form). 


2. Perform the initial PUTs or PUTAL. This changes the vate but does 
not output anything to the screen. 


3. Call DISPW to display the form. 


Note that this requires only one more Form Driver call (the DISPW call). It 
produces a significant reduction in terminal output for some forms. 


3.10 Checking Status — Three Methods 
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Purpose 


Determine result of Form Driver calls. 


Description 


Three methods of checking status of Form Driver calls are discussed in this 
section — calling the Form Driver as a function, calling STAT, and setting up 
status recording variables with SSRV. The first method is compatible with 
the VMS calling standard. You would use the other two methods if you wish to 
be able to report a secondary status when an error is detected. (See Section 2.5 
in Chapter 2 — Checking Call Status.) 
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Programming Technique 


In some situations, an error status does not indicate malfunctioning of your 
program but rather a special situation. For example, your program might be 
using Named Data as the list of valid table entries for a field. Asking the 
Form Driver for the data associated with a Named Data name is the only way 
of determining whether that Named Data item exists. If the Form Driver 
returns an error, your program may use the existence of the error as informa- 
tion itself — that the table entry is not valid. 


In these situations, an error response from the Form Driver is not unexpected 
and does not represent a threat to the continuing execution of the program. 
Any of the three error determination methods is useful in this situation, since 
only the general status is needed. Using STAT is slightly more expensive 
since it requires an extra Form Driver call to obtain the call status. 


In checking for unexpected error situations, no matter which technique you 
use, it is convenient to set up a subroutine to interpret the status of a call and 
take appropriate action. The subroutine checks the status and returns if it 
indicates success. If there is an unexpected error, the subroutine reports the 
error and stops the process in some fashion you determine. Ifthe error is one 
of the types that has a secondary error status associated with it (FDV$_IOL, 
FDV$_IOR, or FDV$_SYS) you may want to report the secondary status 
also. 


Example 


A program that checks the Form Driver’s function value return for an error 
can use the status in a call to the VMS RTL signaling routines, so that the 
message associated with the error is printed. It is still useful to do this ina 
subroutine since the subroutine then obtains the secondary status and also 
signals that. The program call on the subroutine would be used in the follow- 
ing manner (in PL/D: 


CALLFMS = FDVSAWKSP( CHECKWKSP», 2000 )35 
CALL CHKSTA( CALLFMS )35 


The subroutine could be written as follows: 


CHKSTA: PROCEDURE( FMS_VMS_STATUS ) 

LEEK KEE EEE EEE EEE KEKE EEE ERK EE EEE EERE EEE EEE REREEEEEES 
/* Subroutine CHKSTA 

/* Check FMS status by looking at the Parameter which is 
/* a VMS status variable. If there is an errors detach 

/* the terminal to clean up screen and then 

7*® output the error by signalling, 

LEEK HHI EHH EEE HEHEHE HEHE KEE ERE EHH EEE EEE EEE EERE RHEE / 
DCL FMS_VMS_STATUS FIXED BIN(31)3 


DCL SYS#$PUTMSG ENTRY( ANY )5 
DCL MSG_VEC(5) FIXED BIN(31) 


IF MOD(FMS_VMS_STATUS »2)=1 THEN RETURNS 


/* Save the FMS error code in message vector for PUTMSG#/ 
/*® Save the RMS status code in the messagye vector before 


/% making further calls */ 

/* Detach the terminal to clean up screen before printing 
/* error message */ 

MSG_VEC(2) FMS_UMS_STATUS$ 


MSG.VEC(3) 0 /*Reaquired for non-system facility+#/ 
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MSG_VEC(S) = 0 /*In case RMS error msd needs it#/ 
CALLFMS = FOVSSTAT( FMSSTATUS» MSG_VEC(4) ) 

CALLFMS = FDOVS$DTERM( TCA )3 

/%® Set message vector count #/ 

/* OQutrut message(s) */ 

IF MSG_VEC(4) = 
THEN MSG_VEC(1) = 1 /*No secondary status*/ 
ELSE MSG_VEC(1) = 4 


o 


CALL SYS$PUTMSG( MSG_VEC )35 
STOP 


END CHKSTA 


The subroutine could be simplified if the secondary call status were not 
needed. Instead of setting up a message vector, the RTL subroutine 
LIB$SIGNAL or LIB$STOP could be used. For example, the following could 
replace the entire body of the routine above: 


DECLARE LIBSSIGNAL( FIXED BINARY(31) VALUE )5 
CALL LIBSSIGNAL( FMS_YVMS_STATUS )5 


The Sample Application uses two subroutines to check for unexpected errors. 
The first few calls use a subroutine that calls STAT to obtain the status of the 
last Form Driver call. If the status obtained (which is the FMS, system inde- 
pendent status) is greater than zero, then the last call was successful and the 
subroutine returns. If the last call was not successful, the subroutine 
detaches the terminal (to clean up the screen) and prints the error codes 
reported. | 


After the first few calls, SAMP sets up two status recording variables, FMSS- 
TATUS and RMSSTATUS. The Form Driver sets the FMS status in these 
variables for every Form Driver call thereafter. 


The SAMPs use FMSSTATUS in two ways. They call another subroutine that 
checks for unexpected errors. This subroutine does not have to call STAT, but 
merely checks the FMSSTATUS variable. If there is an error, it performs the 
same error reporting as the first subroutine. The second way SAMP uses the 
FMSSTATUS is immediately after a call to PFT in the routine that simulates 
a GETAL call. Since the Form Driver set FMSSTATUS before returning to 
SAMP, SAMP can immediately refer to the value of FMSSTATUS. 


The following is an adaptation (in BASIC) of the two SAMP routines 
described above. Consult the VAX FMS Language Interface Manual to see the 
routines used in several languages. | 


DEF FN.GETSTA 

PERE EHR EEE HEHEHE EE EEE HH EERE I HEH TE RE EH 
!. Subroutine GETSTA 

! Check FMS status by calling STAT. 

! If not success (>0)» Print and stop 

LRH RK HEHEHE HEHEHE EE HEE HERE HERI HEHEHE EEE EERE HEE EH 


CALL FDVSSTAT( FMSSTATUSZ» RMSSTATUSZ ) 
IF FMSSTATUSZ > O THEN FNEXIT 

CALL FOVSDTERM( TCAZ() ) 

PRINT "FDV ERROR." 


PRINT “"+"FMS STATUS:" »sFMSSTATUSZ 
PRINT ""o"RMS STATUS:" »RMSSTATUSZ 
STOP 
FNEND 
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DEF FN.SRVCHK 

PEE RHEE KKH EK EEK EERE EEE RE EERE EEE EEE EE KEKEREREREEE 
! Subroutine SRVCHK 

! Check FMS status by looking at the status 

! recording variables, 

1 EEK HK KEE KHER KEKE EERE EERE EE EE EERE RE EE EERE EE EEE 


IF FMSSTATUSZ > O THEN FNEXIT 
CALL FDV$DTERM( TCAZ() >) 
PRINT "“FDV ERROR." 


PRINT ""s"FMS STATUS:" sFMSSTATUSZ 
PRINT "">"RMS STATUS:" »sRMSSTATUSS 
STOP 
FNEND 


3.11 Paging 


Purpose 


To facilitate collecting multiple pages of data on a single form. 


Description 


Consider the form in the Form Editor used to collect User Action Routine 
names and their associated data. A typical 23-line form might have space for 
five such pairs of data entries. To enter more than five UAR specifications, 
some extension technique must be employed. While scrolling is an excellent 
technique for accessing more data than will fit on a single screen, it is best 
used for accessing data records that can be compressed to a single line, since 
scrolled areas must be scrolled one line at a time. 


The idea behind paging is to have the user enter an entire page of data with- 

out changing the screen, and then clear the fields to enter a new page of data. 

As the user tabs out of the last data field on the form, the form automatically 

advances to the next page. Similarly, if the user backspaces out of the first 

data field on the form, the form automatically moves back to the previous 
_ page (if there is one). 


Since TAB and BACKSPACE are the default FMS keys used to move to the 
next or previous field in a form, no special action is required on the part of the 
operator to move among fields on different pages. Ideally, the operator should 
be able to move freely between pages to correct any previous entry just as he 
would modify a previous entry in a form. To make it clear what data is actu- 
ally being edited, a page number could be displayed at the top of the form, or 
each data record could be preceded by a number that is updated to reflect the 
current page. 


Programming Technique 


Several FMS features are used to produce the paging behavior described 
above. The Form Driver PFT call (Process Field Terminator) is used to simu- 
late GETAL processing. In addition, two special No Echo fields are added to 
the form — one before the first data field, and the other after the last data field. 
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By having the application program know the names of these two fields, it is 
possible for the program to detect when the user moves out of the last data 
field of a form by requesting the name of the current field. Whenever the cur- 
rent field name matches the special first field, the program pages backward, 
similarly when the current field name matches the special last field, the pro- 
gram pages forward. 


Alternatively, you can avoid the two special fields and the GETAL simulation 
by using the ILTRM (1) call with a GETAL call to have the Form Driver 
return illegal terminators. Your program can then identify the illegal termi- 
nator FDV$K_FT_ILG_NXT as a request to go to the next page, since the 
operator is attempting to go to the next field where there is none. A similar 
action can take place for FDV$K_FT_ILG_PRV. The program would have to 
filter out other illegal terminators. 


Example 


This technique is used in the Form Editor to enter Named Data and collect 
field completion UAR data. A subroutine in the Form Editor is used to simu- 
late GETAL processing except that it returns a special terminator code when- 
ever it encounters fields named FIRST and LAST. 
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The following chapter discusses advanced programming techniques in two 
areas of FMS usage. The first section discusses how to enhance FMS perform- 
ance; the second looks at the most effective way to design FMS overlaying 
forms. A working familiarity with these techniques will help FMS users to 
get the most out of FMS. 


3.12.1 FMS Performance 


This section provides information on how to maximize system performance 
while using VAX FMS. Sub-sections include FMS Library Performance and 
Form Driver Ordering of Calls. 


3.12.1.1. FMS Library Performance — The manner in which forms are stored 

and arranged in FMS libraries can either help or hurt performance. By 
observing the following, you are assured that your FMS form libraries will 

not hinder overall system efficiency: 


Compression always compress form libraries when transferring an 
application from the development cycle to the production 
cycle. Use the command: 


$ FMS/LIBRARY/CREATE library library.FLB 


Form Order always insert commonly accessed forms in the library first. 
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Access Method _ use the access method best suited to the application’s 
forms, choosing from the following: 


1. Memory Resident: 


e for forms that are displayed repeatedly such as main 
menus, 


e for times when the number of forms used by the appli- 
cation is small, or when the application is self 
contained. 


2. Dynamic Memory Resident: 


e the dynamic memory resident list is searched first 
when looking for a form, 


e used for forms which are displayed for a selected func- 
_ tion, such as sub-menus and “pages.” 


e also used when a memory resident form needs to be 
replaced at run-time with a form of the same name from 
a form library. 


3. Media Resident: 
e for forms that are seldom accessed, i.e. Help forms, 


e used during application development when forms are 
modified frequently and relinking is not desired. 


3.12.1.2 Form Driver Performance — Form Driver performance can be 
enhanced by using the most current calls available and by correctly ordering 
the Form Driver calls. FMS V2 calls are more efficient in both CPU time and 
VO. Using FDV$INIT causes extra I/O on every Form Driver I/O call. Follow- 
ing these suggestions, and observing the correct ordering of FDV calls, as 
shown below, will maximize Form Driver performance. 
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Ordering of Form Driver Calls 
Inefficient Efficient 


Displaying A Form 


FDV$LOAD FDV$LOAD 

FDV$DISP FDV$DISPW 
Initializing Fields 

FDV$DISP FDV$LOAD 

FDV$PUT FDV$PUTAL 

FDV$PUT FDV$DISPW 

FDV$PUT 

Using Dynamic Memory Resident 
Forms 

FDV$LOAD FDV$READ 

FDV$READ FDV$LOAD 

FDV$DISPW FDV$DISPW 

Checking Status 

FDV$xxxxx FDV$SSRV 

FDV$STAT FDV$xxxxx 

FDV$xxxxx FDV$xxxxx 

FDV$STAT FDV$xxxxx 

FDV$xxxxx 

FDV$STAT 


3.12.2 Designing Overlaying Forms 


This section exists to help the programmer effectively use overlaying forms. 
To design overlaying forms, the programmer should have a clear understand- 
ing of FDV screen management. Therefore, the following sections include a | 
list of FDV screen management rules, and an example of overlaying form 
design. 


3.12.2.1 FDV Screen Management Rules — This section lists screen manage- 
ment rules. It consists of lists detailing when the FDV repairs screens, when 
the screen or workspace is broken, and the workspace repair sequence. 


3.12.2.1.1 Screen repair occurs when: 


e Operator requests a screen refresh 
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e Program calls FDV$RFRSH 

e Returning from HELP 

e Displaying a form 

e Returning from a User Action Routine (UAR) 

e Program calls FDV$PUTxx or FDV$GETxx to fields where the work- 

space that contained the fields was “broken.” 

3.12.2.1.2 The screen or workspace is ”broken” when: — 

e The program calls FDV$GETDL on a line other than the last 

e The program calls FDV$PUTL on a line other than the last 

e The area to clear of an overlaying form clears lines of the form 

e The program calls FDV$CLEAR 
ci Workspace Repair Sequence — The workspace is repaired in this 
order: 


1. All workspaces, marked as displayed, are redisplayed in the order that 
they were attached, except for the current workspace. 


2. The current workspace is redisplayed. 


3.12.2.2  Overlaying Form Design — The following example includes three 
forms, each with its own values for Area To Clear (ATC). The ATC is the area 
to be cleared when a form is displayed. A call to FDV$CDISP clears the entire 
screen, marks all workspaces as “not displayed” and displays the new form. 
However, to overlay forms as shown below, the programmer uses FDV$DISP, 
which displays the new form, clearing only those lines specified by the ATC. 
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Figure 3-1: Overlaying Forms 
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The following table compares different form displaying calls and area to clear 
combinations pertaining to overlaying forms, and their results. 


FDV$CDISP 
ATC 1:23 


FDV$CDISP 
ATC 1:23 


FDV$CDISP 
ATC 0:0 


FDV$DISP 
ATC 1:23 


FDV$CDISP 
ATC 0:0 


FDV$DISP 
ATC 1:23 


FDV$DISP 
ATC 0:0 


FDV$DISP 
ATC 0:0 





Figure 3-2: 
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Chapter 4 
Linking the Application and Setting up the Terminals 


In the development of an FMS application, there are initially three processes: 
e Creating forms and form libraries 

e Writing the application program 

e Writing user action routines (UARs) 


These must, of course, be made into linkable object files. You then can link 
your object program with the Form Driver and, optionally, with any memory- 
resident forms or UARs you wish to include. (See Figure 4-1) 


The Form Driver supports several terminal types and performs screen man- 
agement correctly if you and your program follow certain procedures regard- 
ing setting the terminal characteristics and sending output to the terminal. 


4-1 


Memory- : UAR vector Main program UAR object 
resident module object module module 
forms ; 

— 






Executable 
image 
Form library 


Figure 4-1 Linking the FMS Application 
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4.1 Linking 


4.1.1 Linking with the Form Driver Library 


Linking with the Form Driver Library is automatic, since the Form Driver 
routines are linked as a shared image: 


$ LINK MYPROG 


4.1.2 Linking with Memory-Resident Forms 


Using the Form Application Aid FMS/OBJECT gives you a linkable file of 
memory-resident forms: 


$ FMS/OBJECT formlist.../OUTPUT=MRF.OBJ 


Then: 
$ LINK MYPROG»MRF 


The advantages of keeping forms in memory are: 
1. Faster access 
2. Reduced disk overhead 
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The disadvantages are: 
1. Larger executable disk images 


2. Necessity to relink whenever a form changes 


4.1.3 Linking with a UAR Vector 


You use the Form Application Aid FMS/VECTOR to get a vector module. The 
module contains a table of UARs. You must link the modules with your pro- 
gram so the Form Driver knows where the UARs are when they are needed: 


$ FMS/VECTOR FRMFIL1.FRM»MYLIB.FLB/FORM_NAME=(FORM1 »FORMS3) /OUTPUT=UARS1.0BJ 


$ LINK MYPROG,UARS1 arrlication: 


4.2 Terminal Use in FMS Programs 


4.2.1 Terminal Characteristics | 


To support a variety of terminals, to allow typeahead, and to conform with 
DIGITAL’s long-term terminal software strategy, the Form Driver queries the 
operating system and not the terminal to find the terminal options and cur- 
rent characteristics. This means that you should set VMS’s knowledge of your 
terminal carefully before starting an FMS application program. One method 
of doing this is by issuing the following VMS command before running your 
application: 


$ SET TERMINAL/INOQUIRE - 


VMS will then query the terminal and record the terminal’s characteristics 
correctly. 


Between the issuing of this DCL command and its completion, you should not 
type ahead. Putting the SET TERMINAL/INQUIRE command in your login 
command file is a good idea. 


If your terminal differs from VMS’s knowledge of your terminal, your FMS 
application may not perform correctly. You can see what VMS thinks your 
terminal type is by issuing the following VMS command: 


$ SHOW TERMINAL 


You will see displayed values for terminal attributes: type, width, advanced 
video, ANSI_CRT, and DEC_CRT, among others. Your terminal should be 
either a VT52, or it should have at least the ANSI_CRT attribute. It should 
also have the DEC_CRT attribute as appropriate. See the VAX documenta- 
tion for an explanation of these attributes. Make sure that the terminal width 
and the advanced video option attributes are set correctly for your terminal. 
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4.2.2 Direct Terminal Output 


To optimize output to the terminal, the FMS V2 Form Driver assumes that it 
has sole control of the terminal once the terminal has been attached. Your 
program should not normally send output directly to an attached terminal; 
all output to an FMS terminal should go directly through FMS. Direct output 
to the terminal will likely be displayed at unexpected positions with 
unwanted video attributes, line attributes, or character set. 


If your program changes the cursor position, video attributes, line attributes, 
or character set, subsequent calls on the Form Driver may yield incorrect 
results on the screen. The only circumstances under which you can send out- 
put directly to the terminal and not confuse the Form Driver is if you restore 
any changes you have made before calling the Form Driver again. The 
CLEAR_VA, FIX_SCREEN, and SCR_WIDTH calls may be used for this 


purpose. 


4.2.3 Terminal State at Program End 


Because the Form Driver minimizes output, it will leave the terminal in an 
awkward state if you fail to detach the terminal. Detaching the terminal 
clears video attributes, clears the last line, and positions the cursor at the 
bottom left corner of the screen with the terminal width set to that of the last 
form displayed. 


Note that the design of some terminals makes it impossible to determine 
some of the attributes from the terminal so that neither the Form Driver nor 
your program can restore them once they have been changed: 


e LEDs 
e Character set 
e ‘Screen background 


All these attributes remain in the state last set by the application program’s 
form use and terminal control calls. 


4.2.4 Firmware Bug Workaround 


Many VT100s have a firmware bug that the Form Driver must work around. 
(This workaround itself may appear to be a bug, but it is not.) The firmware 
bug appears when a scrolled area is immediately below a line having the 
double-high or double-wide attribute, and the terminal is in jump scroll 
mode. The bug is that the scrolled lines lose characters, or the terminal may 
enter self-test mode. 


The workaround used by the Form Driver is to set the line above the scrolled 
area to be normal size during the scrolling and then reset it to double high or 
double wide afterward. This may be visually disturbing but does not affect 
your program. The visual effect can be avoided by not setting the line above a 
scrolled area to double high or double wide in the form definition. 
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Chapter 5 
FORM DRIVER CALLS 


The following sections contain descriptions of all Form Driver calls. 


The call format shows the generic form of each call, with the FDV$ prefix you 
must specify with each call name (for example, FDV$ATERM — not just 
ATERM), and any arguments you must (or can) supply. Each argument is 
defined, and it is noted whether the Form Driver reads the argument from 
your program, writes (returns) it to your program, or both reads and writes 
(modifies) it. In your program you terminate a call by pressing the RETURN 
key unless the manual specifies otherwise. 


You always specify an address for an argument rather than the actual data to 
be processed by the call or returned to your program. Each argument defini- 
tion indicates the method of passing the argument: 


e By reference — The address contains the value itself (used for passing 
integers). 


e By descriptor — The address contains the address of a descriptor containing 
necessary information (used for passing character strings or integer 
arrays). 


See the VAX FMS Language Interface Manual for details of the calling 
requirements unique to each language (for example, CALL FDV$ATERM). 
See also the appendix to this manual for a complete list of Form Driver calls 
showing the procedure parameter notation. 


Description 
Describes what the call does, any relationships to other calls, and restrictions 
on the use of the call. 


Status Codes 


Report for each call successful execution of the call or any failures that occur 
during processing of the call. 
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ADLVA 
5.1 Alter Data Line Video Attributes 


FDV$ADLVA (video) . 


video The video attributes code. Set to 1, any or all of bits 0, 1, 2, and 3 specify any or all of 
the Bold, Blink, Reverse, and Underline attributes, respectively (decimal value in 
the range 0 to 15). If the value of this argument is negative, the video attributes are 
restored to their initial states. (Modified. Passed by reference.) 


Attributes Value 

None 

Bold 

Blink 

Blink and Bold 

Reverse 

Reverse and Bold 

Reverse and Blink 

Reverse, Blink, and Bold 

Underline 

Underline and Bold 

Underline and Blink 

Underline, Blink, and Bold 

Underline and Reverse 

Underline, Reverse, and Bold 

Underline, Reverse, and Blink 14 

Underline, Reverse, Blink, and Bold 15 

Restore attributes to initial state -n 
(-n is any negative integer) 
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Description 


Lets you alter the video attributes for the current terminal’s data line. You 
can also specify that these video attributes be restored to their original states. 


The data line video attributes affect the appearance of (1) Form Driver 
messages, which are output to the bottom line of the screen, and (2) other 
lines of text, which are displayed by the execution of PUTL or GETDL calls. 


This call returns the previous contents of video. The data line video attrib- 
utes are returned encoded in the same format you used for the input of the 
new video attributes. 


Status Codes 

FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_TCA No terminal control area (TCA) is defined. 
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AFCX 


5.2 Alter Field Context 


FDV$AFCX (insovr,curpos[,fidnamI[,fididx]]) 


insovr 


curpos 


fidnam 


fididx 


The code indicating whether Insert or Overstrike mode is in effect for a field. 
(Read. Passed by reference.) 


0 = Nochange 
1 = Insert mode 
2 = Overstrike mode 


The cursor position within a field. The cursor position is 1 for the leftmost data 
character in the field, 2 for the next data character to the right, n for the rightmost 
character in the field, andn + 1 for the character position to the immediate right 
of the rightmost data character (the hanging cursor position). Field-marker char- 
acters are not counted by the cursor. The range of the cursor, 1 ton + 1,is limited 
to the number of data characters in the field plus 1. (Read. Passed by reference.) 


For fixed-decimal fields, the range of the cursor is 1to + 2, because the decimal 
point is counted even though it is not a data character. This allows the cursor to be 
positioned on the decimal point, in the hanging cursor position for the left-hand 
part of the field. 


The field name. If fidnam is not specified, the current field is assumed. (Read. 
Passed by descriptor.) 


The field index. (Read. Passed by reference.) 


Description 


Alters the default input mode of a field. This call specifies both the 
Insert/Overstrike mode of the field and the cursor position in the field for any 
GET-type call operation affecting the field. 


The new context specified by this call remains in effect until the field is 
processed as part of any GET-type call. The context is restored to its default 
state when the operator exits the field. Note that if the input processing is 
part of a GETAL or GETAF call, passing through the field in the normal 
course of moving the cursor about on the screen restores the default field 


context. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DSP Form contains only display-only fields. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 
FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in current workspace. 

FDV$_NOF Form contains no fields. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 

FDV$_VAL The value of insovr or curpos is outside the allowed range. 


FORM DRIVERCALLS 5-3 


AFVA 


5.3 Alter Field Video Attributes 


FDV$AFVA (video[,fldnam[,fididx]]) 


video The video attributes code. Set to 1, any or all of bits 0, 1, 2, and 3 specify any or all of 
the Bold, Blink, Reverse, and Underline attributes, respectively (decimal value in 
the range 0 to 15). If the value of this argument is negative, the video attributes are 
restored to their initial states. (Modified. Passed by reference.) 


Attributes Value 
None 0 
Bold 1 
Blink 2 
Blink and Bold 3 
Reverse 4 
Reverse and Bold 5 
Reverse and Blink 6 
Reverse, Blink, and Bold 7 
Underline 8 
Underline and Bold 9 
Underline and Blink 10 
Underline, Blink, and Bold 11 
Underline and Reverse 12 
Underline, Reverse, and Bold 13 
Underline, Reverse, and Blink 14 
Underline, Reverse, Blink, and Bold 15 
Restore attributes to initial state -n 


nis any negative integer) 


fidnam The field name. If fldnam is not apoio: the current field is assumed. (Read. 
Passed by descriptor.) 


fididx The field index. (Read. Passed by reference.) 


Description 


Lets you alter the video attributes of a field in a form. You can also use this 
call to restore these video attributes to their original states. The field video 
attributes immediately change on the screen and remain in effect until you 
either issue another AF'VA call to change them, or you redisplay the form by 
issuing a DISP or CDISP call. 


This call returns the previous contents of video. The video attributes for a 
field are returned encoded in the same format you used for the input of the 
new video attributes. 


If you alter the video attributes of a field by issuing an AFVA call, you cancel 
any input highlighting for the field. That is, if highlighting is in effect for the 
form, it will not be used for this field. You restore highlighting by rene 
the default video attributes of the field. 
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Status Codes 


FDV$_ARG 
FDV$_CAN 
FDV$_FLD 
FDV$_INI 

FDV$_NFL 
FDV$_NOF 
FDV$_SUC 
FDV$_SYS 
FDV$_TCA 


AFVA cont.) 


Incorrect number of arguments. 

Call was terminated by a CANCL call. 

Field does not exist, or index value is invalid for field. 
No workspace is defined. 

No form loaded in workspace. 

Form contains no fields. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 
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ATERM 


5.4 Attach Terminal 


Description 


FDV$ATERM (tca,size,channel[,trmnal[,faketrmtyplI,options]]]) 


tca The name of a terminal control area. The TCA size, contained in the 
| descriptor, must be at least 12 bytes. (Modified. Passed by descriptor.) 

size The size of the TCA in bytes. (Read. Passed by reference.) (Ignored in VMS.) 

channel The logical I/O channel number for the terminal. (Read. Passed by reference.) 

trmnal The name of the terminal to be associated with the TCA. If trmnal is omitted, 


the default is SYS$INPUT. (Read. Passed by descriptor.) 


faketrmtyp § The name of the terminal type the Form Driver assumes for batch use. The 
only valid string supported currently is “VT100”. If this argument is given, 
there is no real input or output to the terminal. (Read. Passed by descriptor.) 


options An integer specifying which Form Driver options are to be associated with 
this terminal. When specifying the option, the integer is a longword with the 
following bits: 
BIT Setting Meaning 
0 The screen shall not be cleared when attaching the terminal. 
1 The Form Driver clears the terminal’s video attributes after 
each call (see CLEAR_VA) 
2 AST support is not required. Requesting this option improves 
performance (see AST considerations). 
3-31 Reserved by Digital. 


Attaches a terminal to the Form Driver. You must issue an ATERM call for 
any terminal the Form Driver needs to access for form processing. This call 
makes the attached terminal the current terminal. 


When you specify a channel, you are specifying a logical channel. FMS asks 
VMS to assign a physical channel. If you want the Form Driver to use a par- 
ticular channel, first issue ATERM and then issue TCHAN. Form Driver log- 
ical channel numbers:are all interpreted modulus 256. 


The channels specified in the Form Driver calls ATERM, LCHAN, and 
LOPEN are strictly local to FMS and have no relationship to Logical Unit 
Numbers used by FORTRAN and BASIC. These channel numbers provide a 
means of reference only. The Form Driver keeps an association list of all logi- 
cal channels currently in use by the application program. Logical terminal 
numbers and logical form library numbers must not conflict; that is, a logical 
terminal channel number cannot be used as a logical form library channel 
number. 


ATERM lets you specify a terminal control area for this terminal. This area 
maintains all necessary information about current terminal characteristics 
and associations. Other calls refer to these areas implicitly or explicitly 
whenever they need to indicate a particular terminal. The terminal must be 
VT200-, VT100- or VT52-compatible. 
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ATERM (cont, 


When the faktrmtyp argument is used in ATERM to attach a fake terminal, 
the terminal so attached is defined as a VT100 type terminal with 65 lines 
and 132 columns (instead of just 24 lines). This gives applications the oppor- 
tunity to use such a fake terminal to produce a line printer report. Calls to 
RETEL, for such a terminal, can access lines 1 through 65. Since the Form 
Language and the Form Editor allow the production of forms only 23 lines 
long, three forms in three workspaces (with appropriate offsets) are necessary 
to produce a full screen of output. 


If the faketrmtyp argument is not supplied (or is null), the terminal specified 
in the trmnal argument is attached in the normal fashion. When faketrmtyp 
is specified as the descriptor of a character string containing “VT100”, no 
actual terminal attachment is made, and the trmnal argument is ignored. 
Any calls for input on the terminal specified by this TCA result in FDV$_ITT 
errors. All output normally directed to the screen is suppressed. However, 
calls that normally produce output, such as CDISP and PUT, still modify the © 
workspace. The Form Driver can then be used as an output formatting tool. 
The faketrmtyp argument causes subsequent calls to RETF L to produce line 
images of what would have been displayed. 


The options argument is useful when you want your program to retain part of 
the current screen while FMS is using another part of the screen. The options 
argument is further defined by setting the two low order bits of the argument. 
Bit 0 is described above. Bit 1 set to 1 directs the Form Driver to reset the 
video attributes and character set of this terminal to the clear state (no video 
attributes and character set shifted in) after every Form Driver call. Bit 1 set 
to 0 directs the Form Driver to leave the attributes of the terminal set 
- between calls to achieve minimal output. 


The use of the second bit in ATERM makes it easier to perform direct screen 
management between Form Driver calls, at the price of additional output on 
every Form Driver call that touches the screen. A program that performs 
direct screen management can choose either to attach the terminal with this 
bit set, or to call FDV$CLEAR_VA at appropriate times. Using 
FDV$CLEAR_VA requires more care on the part of the program, but allows 
the Form Driver to optimize output slightly. 


AST support requires a great deal of overhead in the Form Driver. If your 
application does not need AST reentrant support, setting bit 2 greatly 
reduces the overhead in the Form Driver and will improve its performance. 
However, you must not set this bit if your applications use the Form Driver in 
an AST fashion. This will cause unexpected results. 


In addition, ATERM clears the screen and turns the LEDs off. 
If you do not specify a terminal, the default terminal is attached. 
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Status Codes 


FDV$_ARG 
FDV$_CAN 
FDV$_ICH 
FDV$_ITT 
FDV$_IVM 
FDV$_STA 
FDV$_SUC 
FDV$_SYS 
FDV$_VAL 
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Incorrect number of arguments. 

Call was terminated by a CANCL call. 

Logical channel specified was either in use or invalid. 
Illegal terminal type. 

Not enough virtual memory could be allocated for the TCA. 
Size of specified TCA is too small. 

Successful completion of the call. 

Form Driver encountered system error response. 

Either the faketrmtyp argument was given and it was not 
“VT100”, or the options argument was given and it was not 
within the range of 0-7. 


AWKSP 
5.5 Attach Form Workspace 


FDV$AWKSP (wksp,size) 

wksp The form workspace location. The length (in bytes) recorded in the descriptor, must 
be a value of at least 12. (Modified. Passed by descriptor.) 

size An estimate of the workspace size in bytes. If the size turns out to be too small, the 


Form Driver automatically increases it. (Read. Passed by reference.) 


Description 


Attaches a form workspace to the current terminal. You must issue an 
AWKS?P call for any form your application processes on any terminal. This 
call makes the attached workspace the current workspace. 


The Form Driver uses the 12-byte area specified in the wksp descriptor as 
linkage to an area that it allocates in virtual memory. This area is used to 
store the variable part of a form description. 


The size argument is an estimate of the storage space needed for a loaded 
form. If you underestimate the amount of space you need, the Form Driver 
automatically allocates more space — but a large enough estimate can save 
time. 


You can use the FMS/DIRECTORY command to find out the workspace size 
you need for each form you expect to use. (See the VAX FMS Utilities Refer- 
ence Manual, Chapter 6, Form Application Aids.) 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_IMP Length specified in wksp descriptor is not large enough. 

FDV$_IVM Not enough virtual memory could be allocated for the work- 
space. 

FDV$_SUC — Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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5.6 Ring Terminal Bell 


FDV$BELL 


Description 


Rings the terminal bell. If the current terminal is defined, this call rings its 
bell. If the current terminal is not defined, the call rings the bell on the appli- 
cation program’s default terminal. This call rings the bell regardless of the 
signal mode (see the SSIGQ and SIGOP call descriptions). 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
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5.7 Cancel Call 
FDV$CANCL 


Description 


Causes any other Form Driver call presently being processed on the current 
terminal to be terminated with the error condition FDV$_CAN. 


This call has no effect unless it is executed from an AST service routine or a 
UAR, since no other call can otherwise be executing. 


When executed, this call causes two things to happen: 
1. All I/O operations associated with the current terminal are canceled. 


2. Until the cancellation processing is complete, any other call involving the 
same TCA as that of the call being canceled is itself canceled when issued. 
This action is taken to ensure that all calls issued by a UAR are canceled 
as well. 


As a result of these two activities, the call normally terminates almost imme- 
diately. If a call has called a UAR, however, the call-processing code cannot 
terminate processing until the UAR returns control to the Form Driver. Upon 
return from a UAR, the Form Driver checks to see if the TCA is marked as 
processing a CANCL operation and if it is, the call is terminated. 


If a call is canceled after its UAR has begun executing, any subsequent calls 
the UAR might issue will also be terminated with the status of FDV$_CAN. 


CANCL returns FDV$_SUC whether or not any call is canceled. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_SUC Successful completion of the call. | 
FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA No terminal control area (TCA) is defined. 
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5.8 Clear Screen and Display Form 
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FDVSCDISP (frmnam][,offset]) 


frmnam 
offset 


The name of the form. (Read. Passed by descriptor:) 


The position of the form on the screen. (Read. Passed by reference.) 


© Ifoffset contains 0, the Form Driver positions the form on the screen as specified 
in the form description. 


© If offset contains a nonzero value, the Form Driver moves the form up (if the 
value is negative) or down (if the value is positive) by the amount specified. 


Description 


Executes a CLEAR call and then a DISP call, clearing all forms from the 
screen (marking them as undisplayed) and displaying a new form. If any 
other workspaces are attached to the current terminal, your program can 
redisplay their forms by issuing DISPW calls on their workspaces. See the 
description of the DISP call for additional details. 


Status Codes 


FDV$_ARG 
FDV$_CAN 
FDV$_FCH 
FDV$_FNM 


FDV$_FRM 
FDV$_IFU 


FDV$_INI 

FDV$_IOR 
FDV$_IVM 
FDV$_LIN 
FDV$_SUC 


FDV$_SYS 
FDV$_TCA 


Incorrect number of arguments. | 

Call was terminated by a CANCL call. 

Form was not memory resident, and when the Form Driver 
attempted to search for it in a form library, the current 
library channel was not open. 

Binary form description could not be found either in the form 
library or in the list of memory-resident forms. 

Form description is invalid. 

Workspace cannot be loaded at this time because it is the 
workspace for a currently active UAR. 

No workspace is defined. 

I/O error occurred while Form Driver was reading in the form 
from the form library. The I/O error code is recorded in the 
current state. You can obtain it by issuing the STAT call.* 
Not enough virtual memory could be allocated for the work- 
space. 

Starting offset is invalid. Form does not fit on the screen if 
offset by the amount specified. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 
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CLEAR 


5.9 Clear Screen 


FDV$CLEAR ({line.rLr[,linecnt.rl.r]J]) 


line The number of the first line of the screen to be cleared. A value of zero specifies the 
top of the screen. (Read. Passed by reference.) 


linecnt The number of lines to clear. If you specify 0, all lines from the line you.specified in 
the line argument to the bottom of the screen are cleared. (Read. Passed by refer- 
ence.) 


Description 


Clears all or part of the screen. If line is greater than zero, the screen is 
cleared frem that line down; otherwise, the screen is cleared from the top 
down. If linecnt is greater than zero, it specifies the number of lines to be 
cleared. If it is zero, the screen is cleared to the bottom of the screen. 


A refresh operation (whether by your program or by the operator) following a 
CLEAR operation restores the entire screen, including the cleared area. 


Following the CLEAR operation, the cursor is positioned at the leftmost char- 
acter position on the first line cleared. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by aCANCL call. 

FDV$_LIN Call specifies that some line not on the screen be cleared. 
FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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5.10 Clear Video Attributes 
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FDV$CLEAR_VA 


Description 


Clears the screen of video attributes and sets certain other terminal attrib- 
utes. It is useful when you want your program to write to, or control the 
screen, directly, while a terminal is still attached to FMS. CLEAR_VA per- 
forms the following operations: 


For VT52-type terminals: 
e Shifts in character set. 
For VT100-type terminals: 
e Shifts in character set. 
e Turns off the screen’s video attributes. 
e Sets newline mode. 
e Resets the scrolling area. 
e Sets absolute origin mode. 


This call does not affect the character sets currently selected in GO or G1 for 
VT100-compatible terminals, the width of the screen, or the background color 
of the screen. 


CLEAR_VA should be issued in the following situations: 


e Just before your program starts its own direct screen management 
after FMS has been controlling the screen. This clears the screen of 
any attributes (most importantly, video attributes) that FMS may 
have left, so that your program can start with a known, clean screen. 


e Just before your program calls FMS after your program has changed 
any of the above attributes of the screen. This clears the screen of any 
attributes your program may have left, so that FMS can continue with 
a known screen. 


See also the description of SCR_WIDTH for information on a call that 
informs the Form Driver that your program has changed the width of the 
screen. 


Status codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by CANCL call. 
FDV$_SUC Success. 

FDV$_TCA Nocurrent terminal. 
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DEL 


5.11 Remove Form from Memory-Resident Form List 


FDV$DEL(frmnam) 
frmnam The name of the form. (Read. Passed by descriptor.) 


Description 


Deletes a memory-resident form from the list of memory-resident forms you 
loaded with the READ call. You cannot delete with this call those memory- 
resident forms that are built into the application program. 


If the form you specified is not found, or if it is in the set of forms built into the 
application, this call returns the status code of FDV$_FNM. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FNM _ Binary form description could not be found in the set of mem- 
ory-resident forms that could be deleted (that is, those loaded 
by a READ call). 

FDV$_SUC Successful completion of the call. 
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FDV$DFKBD (defkbd,kbdnum) ; 

defkbd An array of key functions and key codes. (Read. Passed by descriptor.) 

kbdnum The number of entries in the defkbd array. Each entry is a pair of array slots. 
Thus, the length of the array must be at least two times kbdnum. (Read. Passed by 
reference.) 

Description 


The Form Driver has 17 functions and provides default keys to perform these 


functions. However, the user can override these default Form Driver function 


key assignments using defkbd. The defkbdargument is a one-dimensional 
array of words, with kbdnum pairs of entries. (That is, defkbd is expected to 
be two times kbdnumwords.) The first word of each pair is a Form Driver key 
function, as defined below. The second word is a Form Driver key code as 
defined in Chapter 2. Two special key codes are FDV$K_KF_DFLT and | 
FDV$K_KF_NONE. 


1. FDV$K_KF_DFLT declares that the key code for the key function is to be 
the default. (This restores the default after a previous change.) 


2. FDV$K_KF_NONE declares that no key code is to be associated with the 
key function. (The key function is deleted.) 


The key codes in defkbd replace the current key codes for the current TCA. 
Note that not all key functions need be specified in a given call. Only those in 
defkhd are affected. The defkbdarray is merged with the currently active 
table to produce the table used by the Form Driver. 


As a result of the merging of defkbd and the current definitions, no key code 
can be assigned more than one key function. Assigning FDV$K_KF_DFLT to 
a key function assigns all key code defaults to that key function. | 


The following table lists the FDV functions and the default key assignments. 


Function VT100 DFKBD 
Name Description Key Sequence Value 
FDV$K_KF_DLCHR Delete character DELETE 1 
FDV$K_KF_CRSRT © Movecursor right Rightarrow 2 
FDV$K_KF_CRSLF Move cursor left Leftarrow 3 
FDV$K_KF_DLFLD Delete field LINEFEED 4 
FDV$K_KF_INS Set Insert mode PF1 PF3 5 
FDV$K_KF_OVR Set Overstrike mode PF3 6 
FDV$K_KF_GOLD Gold sequence starter PF1 7 
FDV$K_KF_RESET Reset Gold sequence PF1 DELETE 8 
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DFKBD (Cont.) 


Function VT100 DFKBD 


Name Description Key Sequence Value 
FDV$K_KF_RFRSH _ Refresh screen CTRLIR 9 
FDV$K_KF_HELP Help PF2 10 
FDV$K_KF_NXT Next field TAB 11 
FDV$K_KF_PRV Previous field BACKSPACE 12 
FDV$K_KF_NTR Enter Form RETURN or ENTER 13 
FDV$K_KF_SBK Scroll backward Uparrow 14 
FDV$K_KF_SFW Scroll forward Downarrow 15 
FDV$K_KF_XBK Exit scrolled areabackward PF1 Uparrow 16 
FDV$K_KF_XFW Exit scrolled area forward PF 1 Downarrow 17 


The following example shows how to use the DFKBD call to switch the func- 
tions of the RETURN and TAB keys. After this call is executed, RETURN 
(and the ENTER key) will mean Next Field (FDV$K_FT_NXT), and TAB 
will mean Enter Form (FDV$K_FT_NTR). The example is given in 
FORTRAN. 


INTEGER TCA(3) 

INTEGER_*#2 KEYTABLE(4) / FDVSK_KF_NTR» 1033; 
i FOVSKOKFONXT » 1037 / 
CALL FDVSATERM(ZDESCR(TCA) +1291) 

CALL FDVSDFKBD(ZDESCR(KEYTABLE) +2) 


Status Codes 

FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_KEX Too many key codes were defined for some key function. 
FDV$_KIF Illegal key function was given. 


FDV$_KIL Illegal key code was given; that is, the key was not on the 
list in Chapter 2. 


FDV$_KTW Key code was given two separate key functions. 
FDV$_SUC Successful completion of the call. 
FDV$_TCA  Noterminal control area (TCA) is defined. 
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FDV$DISP (frmnan1,offset)) 
frmnam_ The name of the form. (Read. Passed by descriptor.) | 
offset The position of the form on the screen. (Read. Passed by reference.) 


® Ifoffset contains 0, the Form Driver positions the form on the screen as specified 
in the form description. 

© If offset contains a nonzero value, the Form Driver moves the form up (if the 
value is negative) or down (if the value is positive) by the amount specified. 


Description 


Displays a form, clearing the portion of the screen specified as the clear area 
in the form description. Any portion of the screen not cleared is overwritten 
by nonblank portions of the form. If offset has a value of zero, the form is 
positioned as specified in the form description. If offsetcontains a nonzero 
value, the Form Driver moves the form up (if the value is negative) or down (if 
the value is positive) by the amount specified. 


If the form does not fit on the screen (that is, if some portion of background 
text falls outside the area of line 1 through line 23, or line 1 through line 14 
for a non-AVO terminal in 132-column mode), the Form Driver returns the 
FDV$_LIN status code. 


If the form specifies a screen width different from the current width, the 
formwide screen width attribute determines the Form Driver’s action: 


e If the form does not have the screen width attribute, the Form Driver does 
not modify the width. No error can occur with 80-column forms because 
they always fit. Forms having 132 columns do not fit if the screen is cur- 
rently set for 80 columns wide. 


© If the form does have the screen width attribute, the Form Driver always 


modifies the screen width. If the form is an 80-column form, but a 132-col- 
umn form is already displayed on the screen, the 132-column form is 
removed from the screen and marked as undisplayed. The form specified in 
the call is displayed. : 


For terminals not capable of being switched to 132 columns, 132-column 
forms cause an error. 


If the form being displayed specifies that the screen video be modified when 
the form is displayed, the screen video is set as directed, regardless of what 
screen video specifications are associated with any other form already dis- 
played from other attached workspaces. 
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If the background text or fields of the form displayed overlap any background 
text or fields of another form already displayed on the screen, the previous 
text is replaced. If the screen is refreshed, however, the final screen image 
may be changed because the workspaces are redisplayed in the order they 
were attached. The workspace’s form that is current at the time of the refresh 
is displayed properly. 


The following may clarify the screen management role of the Form Driver 
when overlaid forms are present, and when your program issues PUTL and 
GETDL calls to reference lines that are parts of forms. 


Whenever the Form Driver is directed to output a value to the screen by one 
of the PUT-type field calls (PUT, PUTAL, PUTD, PUTDA, or PUTSC), or is 
directed to request input from the operator by one of the GET-type field calls 
(GET, GETAF, GETAL, or GETS(C), it first checks to see if the form containing 
the field is still intact on the screen. If the form has been disturbed in any way, 
the Form Driver redisplays it. 


A form is disturbed in one of two ways: 


1. Part of it has been overlaid by another form (in a subsequent DISPW call, 
RFRSH call or operation, or help request). 


2. Part of it has been overlaid by a PUTL or GETDL call. 


No matter what part of the form has been overlaid, the Form Driver ensures 
that the entire form is displayed. 


The Screen Area to Clear attribute of a form is included in the description of 
the form, so that the form designer should consider how much of the screen 
should be included in this attribute at design time. Even if the form does not 
specify text or field s for a line, the Screen Area to Clear attribute may specify 
that the line be blank when the form is displayed. 


The Form Driver honors the form description whenever the form is refer- 
enced. If you find a form being redisplayed when you do not expect it, it is 
most likely that part of the form has been overwritten. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FCH Form was not memory resident, and when the Form Driver 
attempted to search for it in a form library, the current 
library channel was not open. 

FDV$_FNM _ Binary form description could not be found either in the form 
library or in the list of memory-resident forms. 

FDV$_FRM _ Form description is invalid. 

FDV$_IFU Workspace cannot be loaded at this time because it is the 
workspace for a currently active UAR. 

FDV$_INI No workspace is defined. 
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FDV$_IOR 


FDV$_IVM 
FDV$_LIN 
FDV$_SUC 
FDV$_SYS 


FDV$_TCA 
FDV$_WID 
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1/O error occurred while Form Driver was reading in the form 
from the form library. The I/O error code is recorded in the 
current state. You can obtain it by issuing the STAT call. 
Not enough virtual memory could be allocated for the 
workspace. 

Starting offset is invalid. Form does not fit on the screen if 
offset by the amount specified. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 

The form to be displayed will not fit on the screen (132-col- 
umn form on a VT52). 


DISPW 
5.14 Display Loaded Form 


FDV$DISPW ([offset]) 
offset The position of the form on the screen. (Read. Passed by reference.) 


® Ifoffset contains 0, the Form Driver positions the form on the screen as specified 
in the form description. 

© If offset contains a nonzero value, the Form Driver moves the form up (if the 
value is negative) or down (if the value is positive) by the amount specified. 


Description 


Displays on the current terminal a form already loaded in a workspace. A 
form can be resident in a workspace but undisplayed for any of the following 
reasons: 


e It was previously loaded by a LOAD call. 
e It was removed from the screen as a side effect of a CDISP call. 


e It was a 132-column form that was removed from the screen as a side effect 
of another display call that loaded an 80-column form having the screen 
width attribute (see the description of the DISP call). 


e It was marked as not displayed by the execution of an NDISP call. 


DISPW clears any portion of the screen (possibly offset by the offsetargu- 
ment) that was specified as an area to be cleared in the form description. Any 
other portion of the screen is modified only if it is overwritten by the back- 
ground or field text of the form displayed. See the description of the DISP call 
for additional details. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FCH Form was not memory resident, and when the Form Driver 
attempted to search for it in a form library, the current 
library channel was not open.* 

FDV$_FNM _ Binary form description could not be found either in the form 
library or in the list of memory-resident forms. 

FDV$_INI No workspace is defined. 

FDV$_LIN Starting offset is invalid. Form does not fit on the screen if 
offset by the amount specified. 

FDV$_SUC —_ Successful completion of the call. 

FDV$_SYS = Form Driver encountered system error response. 

FDV$_TCA No terminal control area (TCA) is defined. 

FDV$_WID _ Form being displayed does not fit on the screen (132-column 
form on a VT52). 
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FDV$DPCOM ([dpmode)]) 
dpmode_ A value determining what the decimal point character is to be: 


1 = Comma is accepted exclusively as the decimal point. 
0 = Period is restored to its role as the decimal point. 


(Read. Passed by reference.) 


Description 


Defines the comma, or redefines the period, exclusively, as the decimal point 
for fields containing the signed numeric (N) picture. The decimal point is 
returned to your program as part of the field value (unlike the decimal point 
in fixed-decimal fields). The default is the period. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
FDV$_VAL The value of dpmode is outside the allowed range. 
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5.16 Detach Terminal 


FDV$DTERM (tca) 


tca The name of a terminal control area. (Modified. Passed by descriptor.) 


Description 


Detaches a terminal from the Form Driver. All workspaces associated with 
the terminal are detached, and then the terminal itself is detached. No fur- 
ther Form Driver activity occurs with this terminal after DTERM is exe- 
cuted. Any forms displayed on the detached terminal remain on the screen. 


When a terminal is detached, the character video attributes are cleared, the 
scroll area (VT100s only) is set to the full screen, the bottom line is cleared, 
and the cursor is placed at the leftmost position on the bottom line. 


Normally, when the TCA is detached from the FMS application program, its 
associated terminal is detached from the program. An exception to this rule 
occurs if the channel was specified by the TCHAN call. Because TCHAN, 
alone, specifies a physical channel rather than a logical one, the terminal is 
not detached following a DTERM call. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN = _ Call was terminated by a CANCL call. 

FDV$_FVM _ An error occurred freeing virtual memory allocated to the 
application. 

FDV$_IFU Terminal cannot be detached at this time because it is the 
terminal for a currently active UAR. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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5.17 Detach Form Workspace 


FDV$DWKSP (wksp) 
wksp The form workspace. (Modified. Passed by descriptor.) 


Description 


Detaches a form workspace from the current terminal. Any form that is cur- 
rently displayed remains on the screen. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FVM An error occurred freeing virtual memory allocated to the 
application. 

FDV$_IFU Workspace cannot be detached at this time because it is the 
workspace for a currently active UAR. 

FDV$_INI Workspace does not exist or is not associated with the current 
terminal. 

FDV$_SUC — Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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7 FIX_SCREEN 
5.18 Repair Overwritten Lines of Terminal Screen 


FDV$FIX_SCREEN 


Description 


Programs which perform direct screen management may overlay lines of 
forms displayed by FMS. Calling FIX_SCREEN will repair these lines with a 
minimum of output. FIX_SCREEN is similar to RFRSH, but with two excep- 
tions: FIX_SCREEN does not clear the screen first, and it outputs only those 
lines which it knows to have been cleared. 


Whenever information is sent to a screen field (by a PUT-type call) or 
requested of the screen (by a GET-type call), the Form Driver checks the lines 
of the form. If any line has been cleared as described above, the Form Driver 
then repairs the affected lines of the screen by calling FIX_SCREEN inter- 
nally. Thus, your program need do nothing if the screen has been affected by 
calls on the Form Driver, such as CLEAR, PUTL, GETDL, DISPW, CDISP, or 
DISP, since the Form Driver knows and will fix the screen before the next I/O 
operation affecting fields. 


However, if your program performs direct screen management (that is, it 
affects the screen without calling the Form Driver) the Form Driver will not 
know when the screen has been affected and will not automatically fix it. If 
you wish the Form Driver to restore the screen to the proper state after your 
own direct screen management, you must first clear the lines through the 
Form Driver. One way of doing this is through the CLEAR call. After the 
CLEAR call the Form Driver will know that the lines need to be restored to 
their proper form state. 


FORM DRIVERCALLS 5-25 


GET 


5.19 Get Value for Specified Field 
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FDV$GET (fidval,fidtrm,fidnam[,fididx]) 


fidval The field value. The value consists of data characters, but no field-marker charac- 
ters. If the operator does not enter a character for every position in the field, the 
Form Driver fills the empty positions with fill characters. (Written. Passed by 
descriptor.) 


fidtrm The field terminator that the operator entered to terminate input to the field. 
(Written. Passed by reference.) 


fidnam The field name. (Read. Passed by descriptor.) 
fididx The field index. (Read. Passed by reference.) 


Description 


Waits for the operator to type a value into the field you specified, and records 
the field terminator in fidtrm. If fidnam starts with an asterisk (*), the Form 
Driver prompts the operator for input to the first modifiable field. If the field is 
in a scrolled area, the operation is performed in the current scrolled line for 
that area. 


If the terminator is a function key not reserved for FMS, the form’s function 
key UAR is called. The function key UAR may suppress the terminator, 
ignore it, or change it before subsequent processing occurs. 


If the terminator is not a Previous Field terminator or a function key, the 
Form Driver checks the field for Response Required, Must Fill, and field com- 
pletion UAR requirements. If any requirements are not fulfilled, the operator 
must continue input. 


The value and its terminator are recorded in the workspace and are returned 
to your program. Ifa field value is changed by the operator when this call is 
executed, the status code returned is FDV$_MOD instead of FDV$_SUC. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DSP Form contains only Display Only fields, or the specified field 
is Display Only. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 

FDV$_INI No workspace is defined. 

FDV$_MOD Field value in fidval has been modified by the operator. Oth- 
erwise, this code is the same as FDV$_SUC. 

FDV$_NDS __‘ Form is marked as being not displayed, so no input is 
possible. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_STR Value being returned is too large for the variable allocated 
for it. 
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FDV$_SUC 
FDV$_SYS 

FDV$_TCA 
FDV$_TMO 


FDV$_UAR 
FDV$_UDP 
FDV$_UNF 


GET (cont) 


Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 

Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 

UAR returned illegal code. 

UAR depth exceeded. 

UAR specified but not found. 
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GETAF 


5.20 Get Value for Any Field 


FDV$GETAF (fidval,fidtrm,fidnam[,fididx]) 


fidval The field value. The value consists of data characters but no field-marker charac- 
ters. If the operator does not enter a character for every position in the field, the 
Form Driver fills the empty positions with fill characters. (Written. Passed by 
descriptor.) : 


fidtrm The field terminator that the operator entered to terminate input to the field. 
(Written. Passed by reference.) 


fidnam The field name. (Written. Passed by descriptor.) 
fididx The field index. (Written. Passed by reference.) 


Description 


Allows the operator to move the cursor to any modifiable field in the current 
form (that is, to any field that is not Display Only and not Supervisor Only 
when the Supervisor Only flag is on) and to enter a value in that field only. 
The cursor is initially positioned at the current field and index. The current 
field name and index are updated in the workspace as the operator moves the 
cursor. 


If the terminator is a function key not reserved for FMS, the form’s function 
key UAR is called. The function key UAR may suppress the terminator, 
ignore it, or change it before subsequent processing occurs. 


If the terminator is not a Previous Field terminator or a function key, the 
Form Driver checks the field for Response Required, Must Fill, and field com- 
pletion UAR requirements. If any requirements are not fulfilled, the operator 
must continue input. 


The Form Driver records in the workspace the value and terminator that the 
operator enters, and returns the input to your program. The operator can 
move about the form using the Next Field and Previous Field keys. The call 
ends when the operator modifies one field, presses the ENTER key, or types 
any function key not reserved for FMS. If the operator modifies a field, the 
Form Driver returns the status code FDV$_MOD instead of FDV$_SUC. 


If the form contains scrolled areas, only the current scrolled line for each area 
is accessed by the call. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DSP Form contains only display-only fields. 

FDV$_INI No workspace is defined. 

FDV$_MOD _ Field value in fidval has been modified by the operator. Oth- 
erwise, this code is the same as FDV$_SUC. 

FDV$_NDS ___ Form is marked as being not displayed, so no input is 
possible. 
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FDV$_NFL 
FDV$_NOF 
FDV$_STR 


FDV$_SUC 
FDV$_SYS 

FDV$_TCA 
FDV$_TMO 


FDV$_UAR 
FDV$_UDP 
FDV$_UNF 


(GETAF (cont) 


No form loaded in workspace. 

Form contains no fields. 

Value being returned is too large for the variable allocated 
for it. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 

Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 

UAR returned illegal code. 

UAR depth exceeded. 

UAR specified but not found. 


FORM DRIVERCALLS 5-29 


GETAL 


5.21 Get All Field Values 


FDV$GETAL ([fidval,fidtrm[,fidnaml[,fididx]]]) 


fidval The values of all fields in the current form. The values are returned in the order 
specified in the form description. They consist of data characters but no field- 
marker characters. If the operator does not enter a character for every position in 
the field, the Form Driver fills the empty positions with fill characters. (Written. 
Passed by descriptor.) 


fidtrm The field terminator that the operator entered to terminate input to the field. 
(Written. Passed by reference.) 


flidnam The name of the starting field. (Read. Passed by descriptor.) 
fididx The index of the starting field. (Read. Passed by reference.) 


Description 


Allows the operator to move the cursor to any nonscrolled fields in the current 
form that are modifiable (that is, to any nonscrolled fields that are not Dis- 
play Only and not Supervisor Only when the Supervisor Only flag is on), and 
to enter values in those fields. This call normally positions the cursor at the 
first nonscrolled modifiable field — but if you specify a field with the fldnam 
and fididx arguments, input begins with that field instead. 


The operator can move about the form using the Next Field and Previous 
Field keys. The call ends when the operator presses the Enter Form key ora 
non-FMS function key. The Form Driver processes each field terminator 
according to the description of the PFT call. 


If the terminator is a function key not reserved for FMS, the form’s function 
key UAR is called. The function key UAR may suppress the terminator, 
ignore it, or change it before subsequent processing occurs. 


If the terminator is not a Previous Field terminator or a function key, the 
Form Driver checks the field for Response Required, Must Fill, and field com- 
pletion UAR requirements. If any requirements are not fulfilled, the operator 
must continue input. 


Call processing ends if an error occurs, or if the operator presses a function 
key that is not suppressed by a function key UAR. 


If the operator presses the Enter Form key, but the form has nonscrolled fields 
with Response Required or Must Fill attribute requirements not fulfilled, or 
field completion UARs not satisfied, the Form Driver displays a message at 
the bottom of the screen, signals the operator, positions the cursor at the first 
field still requiring operator input, and awaits further input. (The operator is 
not restricted to entering data in these fields. The Form Driver moves the cur- 
sor only to direct the operator's attention to the fields.) 


Upon completion of the form, the values of all nonscrolled fields (including 
display-only fields) are returned in fidval in the default field access order. 
The final field terminator and the modify flag status are returned as well. 
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GETAL (Cont.) 


If the form contains any scrolled areas, they are ignored by this call. 


Status Codes 


FDV$_ARG 
FDV$_CAN 
FDV$_DSP 


FDV$_INI 
FDV$_MOD 
FDV$_NDS 


FDV$_NFL 
FDV$_NOF 
FDV$_STR 


FDV$_SUC 
FDV$_SYS 

FDV$_TCA 
FDV$_TMO 


FDV$_UAR 
FDV$_UDP 
FDV$_UNF 


Incorrect number of arguments. 

Call was terminated by a CANCL call. 

Form contains only display-only nonscrolled fields, or the 
field specified was display only. 

No workspace is defined. 

At least one field has been modified by the operator. 

Form is marked as being not displayed, so no input is 
possible. 

No form loaded in workspace. 

Form contains no fields. 

Value being returned is too large for the variable allocated 
for it. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 

Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 

UAR returned illegal code. 

UAR depth exceeded. 

UAR specified but not found. 
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GETDL 


5.22 Get Data Line from Terminal 


FDV$GETDL (value,fidtrm[,line[,prompt]]) 
value The data line. (Written. Passed by descriptor.) 


fidtrm The field terminator that the operator entered to terminate input to the field. 
(Written. Passed by reference.) 


line The number of the line on which the operator's input is displayed. If you specify 
zero or omit this argument, the display occurs on the last line of the screen (24 or 
14). (Read. Passed by reference.) 


prompt The data line text. Used as a prompt for the operator. (Read. Passed by descriptor.) 


Description 

Waits for the operator to type a line of text from the terminal. 

The following points are important for you to note: 

e This call does not require a workspace or TCA. 

e The terminator returned is not saved as the current terminator. 

e Any terminator is legal. 

e The text returned has a length in the range of 0 to 132 characters. 


e The text cannot be longer than the current width of the screen used for the 
input — that is, 40, 66, 80, or 132 characters, depending on the screen width 
and the attributes of the line set by any form on the screen. 


e If you specify text for the prompt argument, you reduce the size of the 
allowed input by the length of the prompt. The operator cannot delete the 
prompt. 


e No function key or field completion UAR is called. Help is not available. 
The input editing functions available are the same as for input to a field. 


If line has a value that is not zero, the value specifies the line on the screen to 
be used for the input. Ifline has a value of zero, the bottom line of the screen is 
used. The Form Driver clears the line prior to input and does not restore it 
after input is complete. 


If the data line overwrites part of a form on the screen, the Form Driver may 
redisplay part or all of that form when your program issues the next PUT- 
type or GET-type call to it. 
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Status Codes 


FDV$_ARG 
FDV$_CAN 
FDV$_DLN 


FDV$_STR 
FDV$_SUC 
FDV$_SYS 
FDV$_TMO 


G ETDL (Cont.) 


Incorrect number of arguments. 

Call was terminated by a CANCL call. 

Argument prompt supplied more data than was required, 
and some data was discarded. 

Value being returned is too large for variable allocated for it. 
Successful completion of the call. 

Form Driver encountered system error response. 

Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 
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GETSC 


5.23 Get Current Line of Scrolled Area 


FDV$GETSC (fidnam, fidvall,fidtrm]) 


fidnam A field name identifying the scrolled area. The field name need not specify an input 
field. (Read. Passed by descriptor.) 


fidval The field value. The value consists of data characters but no field-marker charac- 
ters. If the operator does not enter a character for every position in the field, the 
Form Driver fills the empty positions with fill characters. (Written. Passed by 
descriptor.) 


fidtrm The field terminator that the operator entered to terminate input to the field. 
(Written. Passed by reference.) 


Description 


Positions the cursor at the first modifiable field of the current scrolled line 
within the scrolled area containing the named field. But if the previous call 
was a PFT call that processed a field terminator of FDV$K_FT_SPR (Scroll 
to Previous Line), the cursor is positioned at the last modifiable field in the 
line. 


The Form Driver then allows the operator to enter data in the modifiable 
fields of the line, moving from one field to another either by pressing the Next 
Field and Previous Field keys, or by filling a field having the Autotab 
attribute. 


If the terminator is a function key not reserved for FMS, the form’s function 
key UAR is called. The function key UAR may suppress the terminator, 
ignore it, or change it before subsequent processing occurs. 


If the terminator is not a Previous Field terminator or a function key, the 
Form Driver checks the field for Response Required, Must Fill, and field com- 
pletion UAR requirements. If any requirements are not fulfilled, the operator 
must continue input. 


The value of every field in the scrolled line is returned in fidval. When the 
processing of a terminator would cause the cursor to exit the line, the call is 
done. The call is also completed if the operator presses the Enter Form key or 
a function key. 


The most recent field terminator code is returned. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DSP  Formcontains only Display Only fields. 

FDV$_FLD _ Field does not exist. 

FDV$_INI No workspace is defined. 

FDV$_MOD Field value in fldval has been modified by the operator. Oth- 
erwise, this code is the same as FDV$_SUC. 
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FDV$_NDS 


FDV$_NFL 
FDV$_NOF 
FDV$_NSC 
FDV$_SUC 
FDV$_SYS 

FDV$_TCA 
_ FDV$_TMO 


FDV$_UAR 
FDV$_UDP 
FDV$_UNF 


GETSC (cont) 


Form is marked as being not displayed, so no input is 
possible. 

No form loaded in workspace. 

Form contains no fields. 

Field named is not a field in a scrolled area. 

Successful completion of the call. 

Form Driver encountered system error response. 

No terminal control area (TCA) is defined. 

Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 

UAR returned illegal code. 

UAR depth exceeded. 

UAR specified but not found. 
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ILTRM 


5.24 Return Illegal Terminators 


FDVS$ILTRM (trmmod) 


trmmod_A value determining whether illegal terminators are to be returned to your pro- 
gram, or treated as errors: 
1 = Return illegal terminators. 
0 = Do not return illegal terminators. 


(Read. Passed by reference.) 


Description 


Allows your program to receive terminators that are normally illegal in cer- 
tain contexts — for example, a Next Field terminator in the last field of a form 
or a Scroll Forward in a nonscrolled field. You can also restore the default 
state in which illegal terminators are not returned. 


If your program issues ILTRM (1), any illegal terminator (listed below) from 
the current terminal is converted to a special terminator code and is treated 
as if it came from the pressing of a function key. The Form Driver sends the 
code to the form’s function key UAR (if any), where the code can be rejected, 
converted to another terminator, or accepted. If there is no function key UAR, 
the illegal terminator ends input for the current call and is returned to your 
program. 


Following is a list of illegal terminators, all marked by the characters ILG: 


FDV$K_FT_ILG_NXT 
K_FT_ILG_PRV 
K_FT_ILG_ATB 
K_FT_ILG_XBK 
K_FT_ILG_XFW 
K_FT_ILG_SFW 
FDV$K_FT_ILG_SBK 


Status Codes | 

FDV$_ARG Incorrect number of arguments. 

FDV$_CAN = Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
FDV$_VAL The value of trmmod is outside the allowed range. 
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LCHAN 
5.25 Set Channel for Form Library File 


FDV$LCHAN (channel) 


channel The logical I/O channel number for the form library. (Read. Passed by reference.) 


Description 


Specifies the current library logical channel. The current library channel is 
associated with the current terminal, so the terminal must be defined prior to 
execution of this call. Following the execution of LCHAN, the Form Driver 
uses the specified channel for any LOPEN or LCLOS call processing. 


Your program normally issues an LCHAN before executing any other call 
that references the current library channel. The program can issue an 
LOPEN call without issuing an LCHAN first, however, if you choose to spec- 
ify a channel in the LOPEN call. You can use LCHAN to switch from one open 
library to another open library. 


The channels specified in the Form Driver calls ATERM, LCHAN, and 
LOPEN are strictly local to FMS and have no relationship to Logical Unit 
Numbers used by FORTRAN and BASIC. These channel numbers provide a 
means of reference only. The Form Driver keeps an association list of all logi- 
cal channels currently in use by the application program. Logical terminal 
numbers and logical form library numbers must not conflict; that is, a logical 
terminal channel number cannot also be used as a logical form library chan-— 
nel number. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_ICH Logical channel specified was either in use or invalid. 
FDV$_SUC — Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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LCLOS 
5.26 Close Form Library 
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FDV$LCLOS 


Description 


Closes the form library associated with the current library channel. The cur- 
rent library channel is associated with the current terminal, so the terminal 
must be defined prior to the execution of this call. 


Note that if a disk-resident form is displayed on the screen and you then issue 
the LCLOS call, Help forms cannot be accessed from that library. 


Status Codes 

FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_FCH _ Form library is already closed. 
FDV$_ICH Channel specified was invalid. 
FDV$_SUC — Successful completion of the call. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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LEDOF 
5.27 Turn Terminal LED Off 


FDV$LEDOF (ledno) 


ledno The number (in the range 1 to 4) of a LED to be turned off. (Read. Passed by 
reference.) 


Description 


Turns off the specified VT100 light-emitting diode (LED) of the current ter- 
minal if the current terminal is defined. If the current terminal is not defined, 
the call turns off the specified LED of the application program’s default termi- 
nal instead. If the terminal is not a VT100-compatible terminal, the call is 
ignored but a success code is returned. 


If LEDOF is called without a TCA, all the LEDs for the default terminal are 
turned off. | 


If at any time the operator presses the Refresh key, or if your program issues a 
RFRSH call, the LEDs are restored to their previous states. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_SYS = Form Driver encountered system error response. 
FDV$_VAL _ The value of ledno is outside the allowed range. 
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LEDON 


5.28 Turn Terminal LED On 


FDV$LEDON (ledno) 


ledno The number (in the range 1 to 4) of a LED to be turned on. (Read. Passed by 
reference.) 


Description 


Turns on the specified VT100 light-emitting diode (LED) of the current termi- 
nal if the current terminal is defined. If the current terminal is not defined, 
the call turns on the specified LED of the application program’s default termi- 
nal instead. Any other LEDs previously turned on for the default terminal 
are turned off. If the terminal is not a VT100 or a VT100-compatible termi- 
nal, the call is ignored but a success code is returned. 


If at any time the operator presses the Refresh key, or if your program issues a 
RFRSH call, the LEDs are restored to their previous states. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_VAL _ The value of ledno is outside the allowed range. 
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LOAD 
5.29 Load Form without Display 


FDV$LOAD (frmnam) 


frmnam The name of the form. (Read. Passed by descriptor.) 


Description 


Loads a binary form description into a workspace without displaying the 
form. Although the workspace is linked to a TCA, any form loaded by means 
of this call is marked as undisplayed and does not appear on the screen when 
this call is executed. Similarly, the form is not displayed if a RFRSH call is 
executed. 


For a loaded but undisplayed form, all calls requiring operator action are ille- 
gal and return a status of FDV$_NDS. All other calls succeed, but where both 
the screen and workspace would normally be altered or updated by the call, 
only the workspace is altered — the screen is unaffected. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN _ Call was terminated by a CANCL call. 

FDV$_FCH Form was not memory resident, and when the Form Driver 
attempted to search for it in a form library, the current 
library channel was not open. 

FDV$_FNM _ Binary form description could not be found either in the form 
library or in the list of memory-resident forms. 

FDV$_FRM _ Form description is invalid. 

FDV$_IFU Workspace cannot be loaded at this time because it is the 
workspace for a currently active UAR. 

FDV$_INI No workspace is defined. 

FDV$_IOR I/O error occurred while Form Driver was reading in the form 
from the form library. The I/O error code is recorded in the 
current state. You can obtain it by issuing the STAT call. 

FDV$_IVM Not enough virtual memory could be allotted for the 
workspace. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 


FORM DRIVERCALLS 6541 


LOPEN 


5.30 Open Form Library 


FDV$LOPEN (filspc[,channel]) 


filspe The file specification for the form library you want to open. (Read. Passed by 
descriptor.) 


channel The logical I/O channel number for the form library. If this value is zero, the value 
you specified in the most recent LCHAN call for the current terminal remains in 
effect. (Read. Passed by reference.) 


Description 


Opens the form library associated with the channel you specify. If you omit 
the channel specification, the call assumes the current channel. (See also the 
description of the LCHAN call.) 


You must issue this call before any other calls that fetch forms from the form 
library specified by filspe. 


The channels specified in the Form Driver calls ATERM, LCHAN, and 
LOPEN are strictly local to FMS and have no relationship to Logical Unit 
Numbers used by FORTRAN and BASIC. These channel numbers provide a 
means of reference only. The Form Driver keeps an association list of all logi- 
cal channels currently in use by the application program. Logical terminal 
numbers and logical form library numbers must not conflict; that is, a logical 
terminal channel number cannot also be used as a logical form library chan- 
nel number. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FLB _ File specified was not a form library. 

FDV$_FSP _ File specification was invalid. 

FDV$_ICH Channel specified was either in use or invalid. 

FDV$_IOL Form Driver encountered an error while reading the form 
library (it reads the form library to verify that the file is a 

_ form library file). 

FDV$_IOR The Form Driver encountered an error while opening the 
form library. 

FDV$_SUC — Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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| NDISP 
5.31 Mark Form in Current Workspace as Not Displayed 


FDV$NDISP 


Description 


Marks the form in the current workspace as being not displayed. The effect of 
this call is that on subsequent screen refreshes this form is not redisplayed, 
and subsequent GETs for the form are illegal. If the form is already on the 
screen, it remains there. To redisplay the form, your program must issue the 
DISPW call. NDISP is useful if you are using more than one workspace. 


NDISP can be particularly useful in some UARs. Normally, ifa UAR needs to 
use another form to perform its task, it must attach a workspace, issue a DISP 
call to the workspace, and then detach the workspace when it is finished. 
(Note that attaching a workspace is an expensive operation involving the 
allocation of memory from VMS.) If the UAR does not detach the workspace, 
then the UAR working form is shown on every refresh operation thereafter. 


Marking the form in the workspace as being not displayed is more efficient 
than the method described in the preceding paragraph. The workspace can be 
attached and loaded first, before any GETs. Then, when the UAR is activated, 
it can issue a DISPW to display the workspace when it needs it, and then per- 
form an NDISP when it is finished. A Refresh operation at this time would 
bring back the original form, but not the UAR’s working form. 


No error occurs if the form is already marked as being not displayed or if 
there is no form in the workspace; such a form does not affect the screen. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_INI No workspace is defined. 

FDV$_SUC — Successful completion of the call. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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PFT 


5.32 Process Field Terminator 
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FDV$PFT ((fidtrm[,fidnam[,fidval[,nfldnam[,nfldidx]]]])) 
fidtrm The field terminator to be processed. (Read. Passed by reference.) 


fldnam __ A field name identifying a scrolled area. (Ignored in nonscrolled area.) (Read. 
Passed by descriptor.) 


fidval The field values to be displayed if the screen is scrolled during processing of a scrol- 
ling field terminator. (Ignored in nonscrolled area.) (Read. Passed by descriptor.) 


nfldnam_ The current field name after the call has been completed. (Written. Passed by 


descriptor.) 

nfldidx §Thecurrent field index after the call has been completed. (Written. Passed by refer- 
ence.) 

Description 


Processes a field terminator code. This call changes the current field or affects 
the current scrolled line in accordance with the terminator you supply with 
the call. If you omit fidtrm from the call, the Form Driver supplies the most 
recent terminator that the operator entered from the current terminal. 


Note that the PFT call does not itself change the screen or move the cursor. It 
merely changes the current field for the workspace. Your program can then 
get the name of the new current field (from nfldnam) and issue a GET call 
specifying the new field name. The Form Driver then moves the cursor to the 
new field. 


Terminators Action 


FDV$K_FT_NTR=0 _ Tests all nonscrolled modifiable fields to see if they 
satisfy the Response Required and Must Fill attrib- 
utes and calls all field-validation routines for those 
fields. If all fields satisfy the criteria, the Form 
Driver returns the FDV$_SUC code to your pro- 
gram. If any fields do not satisfy the criteria, the 
first such field (in order of access) becomes the cur- 


rent field, and the Form Driver returns the 
FDV$_INC code. 


FDV$K_FT_NXT=1 Makes the next modifiable field (in order of access) 
the current field. If the terminated field is the last 
modifiable field in a scrolled line, the terminator 
behaves like an FDV$K_FT_SNX. If the field is not 
in a scrolled area and there is no next modifiable 
field, the Form Driver returns the FDV$_IFN code. 
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Terminators 
FDV$K_FT_PRV =2 


FDV$K_FT_ATB=3 


FDV$K_FT_XBK =4 


FDV$K_FT_XFW =5 


FDV$K_FT_SNX=6 


FDV$K_FT_SPR=7 


FDV$K_FT_SFW=8 


PFT (Cont.) 


Action 


Makes the previous modifiable field (in order of 
access) the current field. If the field is the first field 
in a scrolled area, the terminator behaves like an 
FDV$K_FT_SPR. If the field is not in a scrolled 
area and there is no previous modifiable field, the 
Form Driver returns the FDV$_IFN code. 


(Autotab attribute) Behaves like an 
FDV$K_FT_NXT. 


Makes the first modifiable field preceding the scrol- 
led area containing fidnam the current field. If 
there is no modifiable field preceding the scrolled 
area, the Form Driver returns the FDV$_IFN code. 


Makes the first modifiable field following the scrol- 
led area containing fldnam the current field. If 
there is no modifiable field following the scrolled 
area, the Form Driver returns the FDV$_IFN code. 


Scrolls forward to next field (from Next Field or 
Autotab terminator in last field of scrolled area). 
Makes the next modifiable field in the scrolled area 
containing fidnam the current field. The area is 
scrolled up, and the new last line is filled with the 
values in fldval, if you supplied them in the call (as 
in a PUTSC call). If you omitted fidval, the Form 
Driver supplies default values. 


Scrolls backward to previous field (from Previous 
Field terminator in first field of scrolled area). 
Makes the previous modifiable field in the scrolled 
area containing fldnam the current field. The area 
is scrolled down, and the new first line is filled with 
the values in fidval, if you supplied them in the call 
(as in a PUTSC call). If you omitted fidval, the 
Form Driver supplies default values. 


Scrolls forward. Makes the first modifiable field in 
the scrolled area containing fldnam the current 
field. If the terminated scrolled line is the last in the 
scrolled area, the area is scrolled up, and the new 
last line is filled with the values in fildval, if you 
supplied them in the call (asin a PUTSC call). If you 
omitted fldval, the Form Driver supplies default 
values. 
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Terminators Action 
FDV$K_FT_SBK=9 — Scrolls backward. Makes the first modifiable field in 


the scrolled area containing fldnam the current 
field. If the terminated scrolled line is the first in the 
scrolled area, the area is scrolled down, and the new 
first line is filled with the values in fidval, if you 
supplied them in the call (asin a PUTSC call). If you 
omitted fidval, the Form Driver supplies default 
values. 


If the field terminator code is not listed above, the Form Driver returns the 
FDV$_UTR code to your program. 


If the Form Driver returns the FDV$_IFN or FDV$_UTR status codes, the 
current field does not change, and nflidnam and nfididx, if you specified them 
in the call, reflect this status. 


Status Codes 


FDV$_ARG 


Incorrect number of arguments. 


FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DLN Value argument supplied more data than was required, and 
some data was discarded. 

FDV$_FLD _ Field does not exist. 

FDV$_IFN Field terminator code cannot be processed in the context 
indicated. . . 

FDV$_INC Form is incomplete. (Returned only when FDV$K_FT_NTR 
is processed.) 

FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_NSC _ Field named is not a field in a scrolled area. 

FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 

FDV$_UTR _ Field terminator code is invalid. | 
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PUT 
5.33 Output Value to Specified Field 


FDV$PUT (fidval,fidnam[,fididx]) 


fidval The field value. The data passed must consist only of the characters to be displayed 
in the data positions of the field. Field-marker characters must not be passed. 
(Read. Passed by descriptor.) 


Note that the Form Driver does not check the validity of the data against the field 
picture. 


fidnam The field name. (Read. Passed by descriptor.) 
fididx The field index. (Read. Passed by reference.) 


Description 


Records the value specified by fldval in the workspace, and, if the workspace 
is marked as displayed, updates the field on the screen with the new data. If 
fidval is shorter than the field, then fidval is justified as the field-justifica- 
tion attribute requires, and the remainder of the field is padded on either the 
right or left, according to that field attribute. The clear character pads the 
field on the screen, and the fill character pads the field in the workspace. 


If fidval is null, the field is filled with its default value. If fldval is too long for 
the field specified, the fidval string is truncated on the right, and the field is 
filled in with the truncated value, from the leftmost portion of the output 
string. The status code FDV$_DLN is displayed if the Form Driver is in 
Debug mode, but FDV$_SUC is returned to your program. 


If a field having the date or time attribute is to be filled with a default value, 
and no default value is defined in the form description, the current date or 
time becomes the default. 


If the field you specify is in a scrolled area, the field is displayed on the current 
scrolled line of that area. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DLN Value argument supplied more data than was required, and 
some data was discarded. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 

FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF _ Form contains no fields. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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PUTAL 


5.34 Output Values to All Fields 


FDV$PUTAL ([frmval]) 
frmval The values for all fields. (Read. Passed by descriptor.) 


Description 


Takes data from frmval, records it in the workspace, and, if the workspace is 
marked as displayed, updates the screen with the new field values. You can 
alter all fields or all nonscrolled fields of the form with this call. 


If the form contains any scrolled areas, they are ignored by this call provided 
frmval is specified. If you omit the frmval value, however, the scrolled areas 
are restored to their default values, and the current scrolled line of each scrol- 
led area is reset to the first line of the area. 


If frmval contains more data than is required to define every field, the excess 
data is discarded, and the Form Driver displays the status code of 
FDV$_DLN if Debug mode is in effect, but returns FDV$_SUC to your pro- 
gram. If frmval contains insufficient data to define every field, the remainder 
are defined by the default values for the fields. 


If a field having the date or time attribute is to be filled with a default value, 
and no default value is defined in the form description, the current date or 
time becomes the default. 


The order of the field values in frmval is specified in the form description. 


Status Codes 


FDV$_ARG Incorrect number of arguments. | 

FDV$_CAN _ Call was terminated by a CANCL call. 

FDV$_DLN Value argument supplied more data than was required, and 
some data was discarded. 

FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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PUTD 
5.35 Output Default to Specified Field 


FDV$PUTD (fidnam[,fididx]) 
fidnam The field name. (Read. Passed by descriptor.) 
fididx The field index. (Read. Passed by reference.) 


Description 


Causes the default value, if any, to be restored to the specified field. If none is 
defined, the field is filled with fill characters in the workspace and with clear 
characters on the screen. The values are displayed only if the workspace is 
marked as displayed. PUTD duplicates a portion of the PUT function and is 
provided to support those languages that do not allow omission of arguments 
from a call. | 


If a field having the date or time attribute is to be filled with a default value, | 
and no default value is defined in the form description, the current date or 
time becomes the default. 


If the field you specify is in a scrolled area, the field default is restored for the 
current scrolled line only. — 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 
FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS ‘Form Driver encountered system error response. 
FDV$_TCA  Noterminal control area (TCA) is defined. 
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5.36 Output Default Values to All Fields 


FDV$PUTDA 


Description 


Causes the default values, if any, to be restored to all fields in a form. If none is 
defined for a field, the field is filled with clear characters on the screen and 
with fill characters in the workspace. Note that the default values are dis- 
played only if the workspace is marked as displayed. This function duplicates 
a portion of the PUTAL function and is provided to support those languages 
that do not allow the omission of all arguments from a call. 


If a field having the date or time attribute is to be filled with a default value, 
and no default value is defined in the form description, the current date or 
time becomes the default. 


If the form contains any scrolled areas, the defaults are restored to the fields 
in the scrolled areas, and the current scrolled line of each area is reset to the 
first line of each area. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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PUTL 
5.37 Output Line to Screen 


FDV$PUTL (text[,line]) 
text The line of text for the data line. (Read. Passed by descriptor.) 
line The number of the line on which the Form Driver displays the data line. If you 


specify zero, the display occurs on the last line of the screen (24 or 14). (Read. 
Passed by reference.) 


Description 


Displays text on the line specified by line; or if the line value is zero, on the 
last line of the screen. The line is always deleted before the text is displayed. 


Normally, the last line is line 24 of the screen. If the screen is in 132-column 
mode, however, and the terminal lacks the Advanced Video Option, the last 
line is line 14. 


If line specifies the last line of the screen, the Form Driver clears the line of 
text when the operator types the next character. If line is not zero, your pro- 
gram has to clear the line. 


The text can be 40, 66, 80, or 132 characters, depending on the current screen 
size and the attributes of the line. If the message does not fit on the current 
screen, it is truncated and the status code of FDV$_DLN is reported if the 
Form Driver is in Debug mode, although FDV$_SUC is returned to your pro- 
gram. A message longer than 80 characters is truncated on a VT52 terminal. 


On a VT100 with the advanced video option, the displayed line has the bold 
video attribute by default. If the terminal does not have the advanced video 
option, the line is displayed in the same video mode as the cursor (underline 
or reverse video), which the operator sets by using the VT100’s Set-Up mode. 
If you specified video attributes in an ADLVA call, those attributes are used 
instead. 


If the terminal is a VT52, the line is displayed in normal video. 


If line overwrites part of a form on the screen, the Form Driver may redisplay 
part or all of that form when your program issues the next PUT-type or GET- 
type call to it. This is true even if the line overwritten was blank or was speci- 
fied only in the area to clear portion of the form. 
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Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DLN Value argument supplied more data than was required, and 
some data was discarded. | 

FDV$_LIN The line argument is invalid. It is either negative or greater 
than the number of lines that can be displayed on the screen 
(24 lines normally, or 14 if in 132-column mode and on a 
VT100 without the advanced video option). 

FDV$_SUC — Successful completion of the call. 

DV$_SYS Form Driver encountered system error response. 
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| PUTSC 
5.38 Output Data to Current Line of Scrolled Area 


FDV$PUTSC (fidnaml[,fidval]) 
fldnam A field name identifying the scrolled area. (Read. Passed by descriptor.) 
fidval The field values. (Read. Passed by descriptor.) 


Description 


Outputs data to the scrolled area containing the field named in fldnam. The 
line in the scrolled area that is displayed is the current scrolled line for that 
area. 


All fields on the current line are updated with fildval. If not enough data is 
supplied in fidval, the remaining fields are set to their default values, or 
cleared if there is no default. If too much data is supplied, the Form Driver 
truncates the data and reports the status code FDV$_DLN if Debug mode is 
in effect, although FDV$_SUC is returned to your program. 


If a field having the date or time attribute is to be filled with a default value, 
and no default value is defined in the form description, the current date or 
time becomes the default. 


The order of the fields in fidval is specified in the form description. 


Status Codes 


FDV$_ARG 


Incorrect number of arguments. 


FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DLN Value argument supplied more data than was required, and 
some data was discarded. 

FDV$_FLD _ Field does not exist. 

FDV$_INI No workspace is defined. 

FDV$_NFL _ No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_NSC __ Field named is not a field in a scrolled area. 

FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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5.39 Read Form into Memory 


FDV$READ (frmnam,mloc,mlocsiz,frmsiz) 

frmnam The name of the form. (Read. Passed by descriptor.) 

mloc The area in which the form is to be stored. (Modified. Passed by descriptor.) 
mlocsiz The size of the memory buffer that begins with mloc. (Read. Passed by reference.) 
frmsiz The size of the form in bytes. (Written. Passed by reference.) 


Description 


Reads a form from a form library into the memory area that you specify and 
adds the form to the head of the list of memory-resident forms known to your 
program. Any subsequent references to the form get the form description 
from mloc rather than from the form library. The size of the form is returned 
in frmsiz. (See also the description of the DEL call.) 


You can have forms with duplicate form names on the list of memory-resident 
forms, but only the form closest to the head of the list can be accessed. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FCH Form was not resident, and when the Form Driver attempted 
to search for it in a form library, the current library channel 
was not open. 

FDV$_FNM _ Binary form description could not be found in the form 
library. 

FDV$_FRM _ Form description is invalid. 

FDV$_IBF Area not large enough to hold the form. 

FDV$_IOR I/O error occurred while Form Driver was reading in the form 
from the form library. The I/O error code is recorded in the 
current state. You can obtain it by issuing the STAT call. 

FDV$_SUC — Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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RET 
5.40 Return Value for Specified Field 


FDV$RET (fidval,fidnam[,fididx)) 


fidval The field value consisting of data characters but no field-marker characters. If the 
operator does not enter a character for every position in the field, the Form Driver 
fills the empty positions with fill characters. (Written. Passed by descriptor.) 


fldnam __ The field name. (Read. Passed by descriptor.) 
fididx The field index. (Read. Passed by reference.) 


Description 


Returns the value of the field you specify from the current workspace. The 
data returned by the RET call is data already accepted from the operator by a 
previous GET-type call, data displayed by a previous PUT-type call, or data 
present by default. Note that unlike the GET call, RET accepts no input from 
the operator. 


Display-only fields are returned by this call. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 
~FDV$_CAN Call was terminated by a CANCL call. 
FDV$_FLD _ Field does not exist, or index value is invalid for field. 
FDV$_INI No workspace is defined. © 
FDV$_NFL No form loaded in workspace. 
~ FDV$_NOF Form contains no fields. 
FDV$_STR _ Value being returned is too large for the variable allocated 
for it. 
FDV$_SUC — Successful completion of the call. 
FDV$_TCA  Noterminal control area (TCA) is defined. 
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5.41 Return Values for All Fields 


FDV$RETAL (frmval) 


frmval The values for all fields. The values returned consist only of the data character 
positions in the fields. No field-marker characters are returned. If data characters 
do not fill a field, the Form Driver fills the remainder of the field with the fill char- 
acter. (Written. Passed by descriptor.) 


Description 


Returns the values of all nonscrolled fields from the current workspace. The 
order in which the fields are returned is specified in the form description. The 
data returned by the RETAL call is data already accepted from the operator 
by a previous GET-type call, data displayed by a previous PUT-type call, or 
data present by default. Note that unlike the GETAL call, RETAL accepts no 
input from the operator. 


Display-only fields are among those returned by this call. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_INI No workspace is defined. 

FDV$_NFL _ No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_STR ‘Value being returned is too large for the variable allocated 
for it. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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5.42 Return Current Context 


FDV$RETCX (atca,awksp,frmnam,uarval,curpos,fidtrm,insovr,hlpnum) 


atca 


awksp 


frmnam 


uarval 


curpos 


fidtrm 


insovr 


hipnum 


The address of the current terminal control area. If this location is zero, no 
TCA is defined. (Written. Passed by reference.) 


Not all high-level languages are capable of handling addresses. 


The address of the current workspace. If this location contains a zero, no 
workspace is defined. (Written. Passed by reference.) 


Not all high-level languages are capable of handling addresses. 
The name of the form being processed. (Written. Passed by descriptor.) 


The value of the associated UAR text, if one is defined. (Written. Passed by 
descriptor.) 


The cursor position within the current field, if any. The cursor position is 1 
for the leftmost data character in the field, 2 for the next data character to 
the right, n for the rightmost character in the field, andn + 1 forthe char- 
acter position to the immediate right of the rightmost data character (the 
hanging cursor position). Field-marker characters are not counted by the 
cursor. The range of the cursor, lton + 1,is limited to the number of data 
characters in the field plus 1. (Written. Passed by reference.) 


For fixed-decimal fields, the range of the cursor is1ton + 2, because the 
decimal point is counted even though it is not a data character. This allows _ 
the cursor to be positioned on the decimal point, in the hanging cursor posi- 
tion for the left-hand part of the field. 


The curpos argument is always nonzero when a UAR is called during field 
processing (a field completion UAR, function key UAR, or help UAR). This 
argument can be zero if the RETCX call is executed when not in a UAR 
doing processing for a field. Zero means that the default position will be 
used for the next field access. 


The curpos argument is not always zero outside UAR processing for a field. 
If your program has previously issued an AFCX call on the current field, 
setting a nonzero curpos, then that nonzero value will be reported. 


The field terminator that the operator last entered either to terminate 
input to a field or to respond to the execution of a WAIT call. (Written. 
Passed by reference.) 


A value indicating whether Insert or Overstrike mode is in effect for a field. 
(Written. Passed by reference.) 


1 = Default 
2 = Insert mode 
2 = Overstrike mode 


The insovr argument is always nonzero when a UAR is called during field 
processing (a field completion UAR, function key UAR, or help UAR). This 
argument can be zero if the RETCX call is executed when a UAR is process- 
ing for a field. Zero means that the default position will be used for the next 
field access. 


The insovr argument is not always zero outside UAR processing for a field. | 
If your program has previously issued an AFCX call on the current field, 
setting a nonzero insovr, then that nonzero value will be reported. 


A value equal to the number of times the operator has pressed the Help key 
for the current field. (Written. Passed by reference.) 
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Description 


Returns the current context of the Form Driver as defined above. Your pro- 
gram can issue this call from a user action routine to determine the context in 
which the UAR is called, although use of RETCX is not limited to UARs. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_STR Value being returned is too large for the variable allocated 
for it. 

FDV$_SUC Successful completion of the call. 
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RETDI 
5.43 Return Named Data by Index 


FDV$RETDI (nmdidx,nmdval[,nmdnam]) 

nmdidx The Named Data index. (Read. Passed by reference.) 

nmdval The Named Data text. (Written. Passed by descriptor.) 
nmdnam The name of the Named Data. (Written. Passed by descriptor.) 


Description 


Returns the Named Data text you specify by index (rather than by name). 
This call also returns the Named Data name. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DNM No Named Data is associated with the specified index. 

FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_STR _ Value being returned is too large for the variable allocated 
for it. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 


FORM DRIVERCALLS 5-59 


RETDN 
5.44 Return Named Data by Name 


FDV$RETDN (nmdnam,nmdval[,nmdidx]}) 

nmdnam The Named Data name. (Read. Passed by descriptor.) 
nmdval_ The Named Data text. (Written. Passed by descriptor.) 
nmdidx The Named Data index. (Written. Passed by reference.) 


Description 


Returns the Named Data text you specify by name (rather than by index). 
This call also returns the Named Data index. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_DNM No Named Data is associated with the specified name. 
FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 


5-60 FORM DRIVER CALLS 


RETFL 


5.45 Return Form Line 


FDV$RETFL (line,value,linlen[,type]) 

line The number of the form line to be returned. (Read. Passed by reference.) 
value The image of the line you request. (Written. Passed by descriptor.) 
linlen The length of the value line in bytes. (Written. Passed by reference.) 


type The type of output you want: 1 for current terminal image (including, for example, 
escape sequences for video) and 0 for line printer image. If type has a value of 0, the 
Form Driver makes the following correspondences. (Read. Passed by reference.) 


1. All video attributes are ignored. 
2. If the line indicated is double width, it is returned with each text een or field 
item centered in the area it would have occupied. 
3. If the line indicated is double size, then the first line is returned as a double- 
width line, and the second line is returned as a line of blanks. 
4. If the line contains any line-drawing graphics, they are converted to standard 
ASCII characters: 
®@ The horizontal bar graphics are converted to ASCII dash characters (-). 
® Vertical bar graphics are converted to ASCII vertical bar characters (| ). 
@ All intersection graphics and corner graphics are converted to ASCII plus 
characters (+). All other characters in alternate character sets remain 
untranslated. 


Description 


Returns the form line you specify with the line argument. Usually, this is one 
of the lines you would see if your program issued a RFRSH call, although your 
program can issue RETFL to display lines from loaded, but undisplayed, 
forms as well. 


If the current terminal has any attached workspaces with undisplayed forms, 
they are normally ignored by this call. But if undisplayed forms are the only 
forms in the attached workspaces, they are all included in generating the line 
image. Thus, your program can use undisplayed forms for report formatting 
purposes. 


When using multiple workspaces, a call to RETFL returns the image of a line 
as it would appear on the screen after a RFRSH. More than one form may 
contribute to the line if forms overlap, and the last form displayed does not 
clear the line. 


If type has a value of 1, the line image returned includes escape sequences 
and control characters to present an exact image of the screen if it were to be 
displayed on the same kind of terminal as the current terminal. The image so © 
returned can be stored in a file and displayed later, or output to an intelligent 
printer that understands the same control sequences as the terminal. 


Since the length of such an image can easily extend beyond 132 characters 
when there are many fields and text blocks on the line (especially if they spec- 
ify varying video attributes and character sets), the buffer used has a capac- 
ity of 4000 bytes, which should be sufficient for all but multiple overlaid 
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forms on a single line. If the buffer overflows, the error FDV$_LLI is 
returned. Saving, and later displaying, a very long line may cause problems 
due to RMS or VMS restrictions on file record size or I/O record sizes. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_INI No workspace is defined. 

FDV$_LIN Call specifies that some line not on the screen was requested. 

FDV$_LLI The Form Driver’s internal buffer was not large enough to 
store the line image requested. The line image returned is 
truncated. 

FDV$_STR _ Value being returned ‘is too large for the variable allocated 
for it. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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RETFN 
5.46 Return Current Field Name 


FDVS$RETFEN (fidnam[,fididx]) 
fidnam The field name. (Written. Passed by descriptor.) 
fididx The field index. (Written. Passed by reference.) 


Description 


Returns the current field name and index from the current workspace. If the 
field is not indexed, RETFN returns an index value of zero. If there is no cur- 
rent field, the Form Driver returns a null string of characters for the field 
name. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_STR Value being returned is too large for the variable allocated 
for it. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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5.47 Return Field Names in Order 


FDV$RETFO (fidnum,fidnam,fididx) 


fldnum The nth field in the form, where n includes the number of any identically named 
indexed fields present. (Read. Passed by reference.) 


fidnam The name of the field corresponding to fldnum. (Written. Passed by descriptor.) 
fididx The field index corresponding to fidnum. (Written. Passed by reference.) 


Description 


Returns the name and index of the nth field in the form — where n includes 
the number of any identically named indexed fields present. If you want the 
fifth field in the form (n = 5), it could have a unique name, or be, for exam- 
ple, FIELD1 indexed down to the fifth field called FIELD1. 


The field names can be in scrolled areas, but a field name in a scrolled area is 
returned only once, unless the field also happens to be indexed. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN = Call was terminated by a CANCL call. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 
FDV$_INI No workspace is defined. 

FDV$_NFL No form loaded in workspace. 

FDV$_NOF  Formcontains no fields. 

FDV$_SUC — Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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RETLE 
5.48 Return Length of Specified Field 


FDV$RETLE (fidlen,fidnam|[,fididx]) 


fidlen The length of the field. The length is defined as the number of data positions in the 
field. The number of field-marker characters on the field has no effect in the deter- 
mination of the length of the field. (Written. Passed by reference.) 


fidnam The field name. (Read. Passed by descriptor.) 
fididx The field index. (Read. Passed by reference.) 


Description 


‘Returns the length of the field you specify. The length of a field is the number 
of data characters in the field exclusive of any field-marker characters. 


Status Codes 


FDV$_ARG __ Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FLD _ Field does not exist, or index value is invalid for field. 
FDV$_INI No workspace is defined. 

FDV$_NFL _ No form loaded in workspace. 

FDV$_NOF Form contains no fields. 

FDV$_SUC Successful completion of the call. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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RFRSH 
5.49 Refresh Screen 
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FDV$RFRSH 


Description 


Redisplays all forms currently marked as being displayed on the screen. This 
operation is identical to the one initiated by the operator’s pressing of the 
Refresh key. If several forms are on the screen, they are redisplayed in the 
order that their workspaces were attached, except that the current work- 
space’s form is always displayed last. 


A screen refresh also restores the keypad mode. In addition, the refresh oper- 
ation restores the terminal LEDs to the state they were in before the refresh 
occurred. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_FCH Form wasnot resident, and when the Form Driver attempted 
to search for it in a form library, the current library channel 

. was not open. 

FDV$_INI No workspace is defined. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 
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SCR_WIDTH 
5.50 Set Screen Width 


FDV$SCR_WIDTH (width) 


width An integer specifying the current width of the screen; must be either 80 or 
132. (Read. Passed by reference.) 


Description 


Informs the Form Driver that your program has changed the width of the 
screen from the value last known to the Form Driver. Your program must also 
inform the operating system when it changes the screen width. The Form 
Driver does not change the screen or inform the operating system of screen 
width changes as a result of this call. However, the Form Driver always 
informs the operating system when other calls to the Form Driver change the 
screen width. Your program can query the operating system at any time for 
this information. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by CANCL. 
FDV$_SUC Success. 

FDV$_TCA  Nocurrent terminal. 
FDV$_VAL Width was not 80 or 132. 
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SIGOP 
5.51 Signal Operator 


FDV$SIGOP 


Description 


Signals the operator from the application program. Depending on the current 
signal mode for the terminal, either the terminal bell is rung or the video of 
the terminal is reversed until the operator next types a valid character (any 
character that does not generate another Form Driver signal). See also the 
description of the SSIGQ call. 


This signaling is automatically performed prior to each error message issued 
by the Form Driver. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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SPADA 
5.52 Set Keypad to Application Mode 


FDV$SPADA (mode) 


mode A value determining the keypad mode: 
® If mode contains 0, keypad = numeric mode. 
® If mode contains 1, keypad = application mode. 


Any other values are erroneous. (Read. Passed by reference.) 


Description 


Sets the terminal keypad mode. In numeric mode, the terminal keypad keys 
act as normal keys, returning the characters inscribed on them. When the 
keypad is in application mode, the keypad keys act as field terminator keys. 
The Form Driver resets the keypad of the current terminal to the selected 
mode whenever a Refresh operation occurs. 


If no current terminal is in effect (TCA not defined), the default terminal is 
used in this call. Prior to the application making this call, the status of the 
keypad is determined by its VMS status. See the SET and SHOW TERMI- 
NAL commands in the VAX/VMS Command Language User’s Guide. 


Status Codes 


FDV$_ARG _ Incorrect number of arguments. 

FDV$_CAN _ Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
FDV$_VAL _ The value of mode is outside the allowed range. 
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SPOFF 
5.53 Turn Supervisor-Only Mode Off 


FDV$SPOFF 


Description 


Sets the supervisor-only mode flag to Off. Following this call, the operator can 
alter fields marked as Supervisor Only in the form descriptions. The supervi- 
sor-only flag is altered only for the current terminal. There is a separate 
Supervisor Only flag for each terminal. 


The supervisor-only flag is set to On when the terminal is first attached. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN _ Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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SPON 
5.54 Turn Supervisor-Only Mode On 


FDV$SPON 


Description 


Sets the supervisor-only mode flag to be set to On. Following this call, fields 
marked as Supervisor Only in the form descriptions are treated as display- 
only fields. The Supervisor Only flag is altered only for the current terminal. 
There is a separate Supervisor Only flag for each terminal. 


The supervisor-only flag is set to On when the terminal is first attached. 


Status Codes 


FDV$ _ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 
FDV$_TCA No terminal control area (TCA) is defined. 
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SSIGQ 


5.55 Set Signal to Quiet Mode 


FDV$SSIGQ (sigmd) 
sigmd The signal mode value. (Read. Passed by reference.) 
0 = Bell 


1 = Reverse video 


Description 


Specifies the signal mode for the current terminal. If the signal mode is 0, the 
terminal bell is rung when you later issue the SIGOP call or the Form Driver 
issues any error message. If the mode is 1, the screen video is reversed when 
the signal occurs and automatically reverts back to the original video mode 
when the operator types the next valid character. See also the description of 
SIGOP. 


If the signal mode is 1, and the Form Driver does not know what the screen 
video attribute of the terminal is, the Form Driver sets the terminal to nor- 
mal video (white characters on black background). The Form Driver knows 
the screen video attribute from then on regardless of any changes caused by 
subsequent form displays. 


Ifthe terminal is a VT52, the terminal bell is the signaling mode regardless of 
the mode setting. Attempts to specify video reversal as the signal mode for 
VT52-compatible terminals are ignored. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 
FDV$_TCA Noterminal control area (TCA) is defined. 
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SSRV 
5.56 Specify Status Reporting Variables 


FDV$SSRV ((status[,iostat]]) 


status The value of the general status. This address becomes the general status reporting 
variable. (Written. Passed by reference.) 


iostat The value of the I/O status. This address becomes the I/O status reporting variable. 
(Written. Passed by reference.) 


Description 
Records the addresses of two variables in the current terminal’s TCA: 


e The address of a variable in which each subsequent call’s I/O status is to be 
recorded 


e The address of a variable in which each subsequent call’s normal status is 
to be recorded 


Following the execution of any call, if either address is not location 0, the 
appropriate call status is stored in the status variable. You can use this call to 
set up automatic status reporting instead of using the STAT call or VMS sta- 
tus returns. 


The status variables must be 32-bit integers on all VAX systems. 


It is the application program’s responsibility to ensure that after it issues this 
call, the addresses specified remain valid until the call is issued again specify- 
ing zeros for addresses. When you specify zeros as addresses (or when you do 
not specify any arguments), further status reporting is discontinued. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 
FDV$_TCA  Noterminal control area (TCA) is defined. 
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STAT 
5.57 Return Status from Last Call 


FDV$STAT (status[,iostat]) 


status The value of the general status. (Written. Passed by reference.) 
iostat The value of the I/O status. (Written. Passed by reference.) 
Description 


Returns the status code for the previous call. Note that a STAT call following 
a previous STAT call returns the result of the previous STAT. That result is 
almost always success. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 
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STERM 


5.58 Set Current Terminal 


FDV$STERM (tca) 


tca The name of a terminal control area. (Modified. Passed by descriptor.) 


Description 


Makes a specified attached terminal (as indicated by its terminal control 
area) the current terminal. Your program must have previously attached the 
terminal with an ATERM call with the TCA specified. 


Changing the current terminal also causes the current workspace to be 
changed to the workspace most recently associated with the new current ter- 
minal. If no workspace is attached to that terminal, then after the execution 
of this call the current workspace is undefined. 


Status Codes 


FDV$_ARG _Inéorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC — Successful completion of the call. 

FDV$_TCA The TCA supplied is not attached or is invalid. 
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STIME 


5.59 Set Field Entry Timeout 


FDV$STIME (time) 


time The number of seconds the Form Driver waits for the operator to respond to a GET- 
type call. This parameter is optional, and defaults to 0.(Read. Passed by reference.) 


Description 


Specifies the number of seconds the Form Driver waits for the operator to 
respond to a GET-type call. Execution of this call cancels the effect of any pre- 
vious STIME call for the current terminal. A negative or zero time value 
causes the Form Driver to wait indefinitely for input (the default). A separate 
STIME is associated with each terminal. 


After an STIME call, the Form Driver resets the timeout value for each char- 
acter in a field. Thus, if a field has ten characters in it and the timeout value is 
15 seconds, the operator has 15 seconds to respond with the first character 
and 15 seconds to respond with each of the other nine characters in the field. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by a CANCL call. 
FDV$_SUC Successful completion of the call. 
FDV$_TCA  Noterminal control area (TCA) is defined. 
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SWKSP 
5.60 Set Current Workspace 


FDV$SWKSP (wksp) . 
wksp The form workspace location. (Modified. Passed by descriptor.) 


Description 


Makes the attached workspace you specify the new current workspace. If the 
workspace you specify is associated with a different terminal, the current 
terminal is changed as well. Your program must have previously attached 
the specified workspace to a terminal TCA by issuing an AWKSP call. | 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. . 
FDV$_INI The workspace specified is not attached or is invalid. 
FDV$_SUC — Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 
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TCHAN 


5.61 Set Terminal Channel 


FDV$TCHAN (Channel) 


channel The number of a physical I/O channel (not a logical I/O channel) to be associated 
with the current terminal. (Read. Passed by reference.) 


Description 


Specifies a physical terminal channel to be used for the current terminal. 
When your program issued ATERM, the Form Driver allocated a physical 
channel to correspond to the logical channel specified. TCHAN specifies a 
physical channel different from the one allocated by ATERM. 


TCHAN requires that the TCA be attached before your program issues this 
call. 


The previous physical channel is released when your program issues this call. 
The logical channel number of the previous channel (the channel number | 
specified in the ATERM call) is also released. 


NOTE 


If your program issues TCHAN and later detaches the associ- 
ated TCA, the terminal is not released. Any channel specified 
by means of the TCHAN call must be released by your 
program. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_ICH Logical channel specified was either in use or invalid. 
FDV$_SUC — Successful completion of the call. 

FDV$_TCA Noterminal control area (TCA) is defined. 
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| USER_REFRESH 
5.62 Set up User Refresh Routine 


FDV$USER_REFRESH(Irfr_address]) 


rfr_address _ Address of a user-supplied routine to refresh part of the terminal screen. If 
this argument is specified, all subsequent Form Driver refresh operations 
will call the user-supplied routine first. If this argument is null or not speci- 
fied, no user refresh routine will be called on subsequent Form Driver refresh 
operations. 


Description 


Helps a program maintain part of the terminal screen independent of the 
Form Driver, when the Form Driver normally overwrites part or all of the 
screen. For example, when the Form Driver must perform a refresh operation 
for the current terminal, the terminal’s screen is first cleared and set to the 
proper width and background. Then all the workspaces marked as displayed 
are redisplayed. If your program is maintaining part of the screen, the refresh 
operation’s screen clear automatically deletes your program’s part from the 
screen. 


When the Form Driver refreshes the screen, it calls your refresh routine, if 
one has been supplied in a call to USER_REFRESH. Your routine should 
clear and write its own part of the screen, call CLEAR_VA, if necessary, and 
then return. The Form Driver then redisplays the displayed workspaces. This 
allows the refresh function to affect both your program’s screen area and the 
Form Driver's area. 


The Form Driver calls your refresh routine in four circumstances: 
e Your program calls RFRSH. 
e The operator presses the Refresh key during data entry. 


e Help processing or UAR processing caused some part of the Form Driver's 
screen to be overlaid. That is, a form marked as displayed was overlaid by a 
help form or by a form displayed by a Field Completion UAR, Function Key 
UAR, or Pre-Help or Post-Help UAR. 


Prior to returning to normal data entry after the help or UAR sequence, the 
Form Driver calls your refresh routine and then redisplays the required 
forms. If a help form or UAR form does not overlay a displayed form, the 
Form Driver does not call your refresh routine. You should design your pro- 
gram so that if a help form or a UAR action overlays your program’s screen 
area, it should also overlay the Form Driver's screen area. 


e The terminal width is changed when a new form is displayed by using a 
CDISP, DISP, or DISPW call, or by using a help form display operation. 


The Form Driver calls your refresh routine as if it were a UAR. The refresh 
routine behaves exactly like a UAR, except that it must not change the termi- 
nal width. The Form Driver restores the current terminal, workspace, and 
field. 
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USER_REFRESH (Cont.) 
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An application program should make a call to USER_REFRESH specifying a 
user routine before starting the separate screen display. A second call should 
be made to USER_REFRESH without any argument when your program has 
completed its separate screen display. 


Status codes 


FDV$_ARG Incorrect number of arguments. 
FDV$_CAN Call was terminated by CANCL. 
FDV$_SUC Success. | 

FDV$_TCA Nocurrent terminal. 
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WAIT 
5.63 Wait for Operator 


FDV$WAIT ([fidtrm)) 


fidtrm The returned field terminator that the operator entered to terminate the wait con- 
dition. (Written. Passed by reference.) 


Description 


Waits until the operator signals to proceed by pressing any terminator key. 
This call allows the Form Driver to synchronize the application program with 
the pace of the operator. 


If the terminator is a function key not reserved for FMS, and if a form is 
loaded in the current workspace and has a function key UAR, the Form 
Driver calls that UAR. The function key UAR may suppress the terminator, 
ignore it, or change it before subsequent processing occurs. When a termina- 
tor is accepted, it is recorded in the workspace as the most recent terminator 
entered. 


Status Codes 


FDV$_ARG Incorrect number of arguments. 

FDV$_CAN Call was terminated by a CANCL call. 

FDV$_INI No workspace is defined. 

FDV$_SUC Successful completion of the call. 

FDV$_SYS Form Driver encountered system error response. 

FDV$_TCA  Noterminal control area (TCA) is defined. 

FDV$_TMO Operator took longer to respond than allowed by the timeout 
value associated with the current terminal. 

FDV$_UAR UAR returned illegal code. 

FDV$_UDP UAR depth exceeded. 

FDV$_UNF UAR specified but not found. 
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APPENDIX A 
VAX FMS Form Driver Calls 


A.1 VAX Language-independent Notation 


Form Driver routines are invoked according to rules specified in the VAX 
Procedure Calling and Condition Handling Standard (Appendix C of the VAX 
Run-Time Library Reference Manual). The complete notation for describing 
VAX calls is documented in Appendix C of the VAX Guide to Creating 
Modular Library Procedures. 


Form Driver routines can be invoked as subroutines or as functions: 
Asasubroutine CALL FDV$xxx (parameter1, parameter?2....) 


as a function VMS-stat.wle.v = FDV$xxx (parameterl1, 
parameter?2....) 


Access type, data type, passing mechanism, and parameter form are assigned 
to each parameter in a prescribed order: 


<parameter-name>.<access type><data type>.<passing mechanism><parameter form> 


Example 


For the FDV$GET call the fidval, fidtrm, fldnam, and fididx parameters 
are described as follows: 


FDV$GET (fidval.wt.dx1,fidtrm.wl.r,fldnam.rt.dx1[,fididx.rl.r] 


The notation for each parameter is explained below. Note that every Form 
Driver call returns a VMS status code in the form VMS_stat.wlc.v. 


Parameter <access type> 


fidval 


fidtrm 


| fidnam 


fididx 


A-2 


w Write-only 
access 


w Write-only 


. <data type> <passing mechanism> <parameter form> 

t Character-coded text d By descriptor x1 Fixed-length or 

string dynamic string 
descriptor 


1 Longword integer r By reference — 


access (signed) 
r Read-only _t Character-coded text d By descriptor x1 Fixed-length or 
access string dynamic string 
. descriptor 
r Read-only 1 Longword integer r By reference — 
access (signed) 
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A.2 Procedure Parameter Notation For Form Driver Calls 


FMS uses a subset of the VAX procedure parameter notation. The following 
table explains the notation used for access type, data type, passing mecha- 
nism, and parameter form. 


Notation 


Notation 


a 
] 


le 


Notation 


d 


Notation 


a 
xl 


<access type> 


Read-only access 
Write-only access 


Modify access 


<data type> 


Virtual address 


Comments 


Parameters for input 
Parameters for output 


Parameters for both input and output 


Longword integer (signed) 


Longword return status 


Character-coded text string 


Aligned bit string 
Word integer (signed) 


<passing mechanism> 


By descriptor 


By reference 


<parameter form> 


Comments 


FMS passing mechanism for character 
strings and integer arrays 


FMS passing mechanism 


Array reference or descriptor 


Fixed-length or dynamic string descriptor 
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- Call 
ADLVA 


AFCX 


AFVA 


ATERM 


AWKSP 


BELL 


CANCL 


VAX FMS Form Driver Calls 


Procedure Parameter Notation 


FDV$ADLVA (video.ml.r) 
video video attributes code of data line 


Alters the data line video attributes. You can specify Blink, Bold, Reverse, 
and/or Underline. 


FDV$AFCX (insovr.rl.r,curpos.rl.r[,fidnam.rt.dx1[,fldidx.rl.r]]) 


insovr Insert/Overstrike mode of field 
curpos cursor position within field 
fidnam field name 

fididx field index 


Alters the default field context of the specified field. You can specify Insert or 
Overstrike mode and cursor position in the field before any GET operation 
involving that field. 


FDVSAFVA (video.m1.r[,fidnam.rt.dx1[,fididx.rl.r]]) 


video video attributes code for field 
fidnam field name 
fididx field index 


Alters the field video attributes. 


FDV$ATERM (tca.ml.da,size.rl.r,channel.rlLr[,trmnal.rt.dx1 
[,faketrmtyp.rt.dx1[,options.rLr]]]) 

or 
FDV$ATERM (tca.mt.dx1,size.rl.r,channel.rl.r[,trmnal.rt.dx1 
[,faketrmtyp.rt.dx1[,options.rLr]]]) 


tca terminal control area 

size size 

channel logical I/O channel number for terminal 
trmnal name of terminal 

faketrmtyp name of terminal used for batch processing 
options integer specifying Form Driver options 


Attaches a terminal to the Form Driver for processing forms over a specific, 
logical I/O channel, names a TCA for that terminal, and specifies the size of 
the TCA. 


FDV$AWKSP (wksp.ml.da,size.rl.r) 
or 
FDV$AWKSP (wksp.rt.dx1,size.rl.r) 


wksp form workspace 
size estimate of workspace size 


Attaches a form workspace to a list of workspaces associated with the current 
TCA, specifies the size in bytes, and establishes that workspace as the current 
workspace. 


FDV$BELL 
Rings the terminal bell. 


FDV$CANCL 
Cancels any other call presently being processed on the current terminal. 
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CDISP 


CLEAR 


CLEAR_VA 


DEL 


DFKBD 


DISP 


DISPW 


DPCOM 


DTERM 


FDV$CDISP (frmnam.rt.dx1[,offset.rl.r]) 


frmnam form name 
offset number controlling placement of form on screen 


Clears the screen and displays a form. The display position may be offset from 
the original form description. . 


FDV$CLEAR ([line[,linecnt]]) 


line line number of first line to clear 
linecnt number of lines to clear 


Clears the entire screen unless otherwise specified with the arguments. 
FDV$CLEAR_VA 

Clears the screen video attributes. 

FDV$DEL (frmnam.rt.dx1) 

frmnam form name 

Deletes a form from the list of memory-resident forms. 

FDV$DFKBD (defkbd.rw.da,kbdnum.rl.r) 


defkbd array of key functions and key codes 
kbdnum __ number of pairs of key functions and associated key codes in 
defkbd array 


Redefines the FMS keypad function keys. 
FDVS$DISP (frmnam.rt.dx1[,offset.rl.r]) 


frmnam form name 
offset number controlling placement of form on screen 


Clears the portion of the screen specified as the “clear area” in the form 
description and displays a form. The display position can be offset from the 
original form description. 


FDV$DISPW ((offset.rl.r]) 
offset number controlling placement of form on screen 


Clears the portion of the screen specified as the “clear area” in the form 
description and displays the form that is already loaded in the workspace. The 
display position can be offset from the original form description. 


FDV$DPCOM ([dpmode]) 
dpmode _ value defining decimal point in signed-numeric fields 


Defines the comma, or redefines the period, as the decimal point in fields con- 
taining signed-numeric field-validation characters. 


FDV$DTERM (tca.ml.da) 
or 
FDV$DTERM (tca.rt.dx1) 
tca terminal control area 


Detaches a terminal from the Form Driver, and detaches any workspaces asso- 
ciated with the terminal. 
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A-6 


DWKSP 


FDV$DWKSP (wksp.ml.da) 
or 

FDV$DWKSP (wksp.rt.dx1) 

wksp form workspace 


Detaches a form workspace from the list of workspaces associated with the 
current terminal. 


FIX_SCREEN FDV$FIX_SCREEN 


GET 


GETAF 


GETAL 


GETDL 


GETSC 


ILTRM 


Repairs overwritten lines on the terminal screen. 
FDV$GET (fidval.wt.dx1,fldtrm.wl.r,fidnam.rt.dx1[,fldidx.rlr]) 


fidval field value 
fidtrm field terminator 
fldnam field name 
fididx field index 


Positions the cursor in the initial cursor position of a specific modifiable field 
and waits for the operator to enter a value. 


FDV$GETAF (fldval.wt.dx1,fidtrm. wl.r,fidnam.wt.dx1[,fldidx.wl.r]) 


fidval field value 
fidtrm field terminator 
fidnam ending field name 
fididx ending field index 


Positions the cursor in the current field in the form and waits for the operator 
to enter a value in any field. 


FDV$GETAL ((fidval.wt.dx1,fidtrm.wLr[,fldnam.rt.dx1[,fldidx.rLr]]]) 


fidval returned values of all fields in form 
fidtrm field terminator 
fidnam starting field name 


fididx starting field index 


Positions the cursor in the first modifiable field in a form unless otherwise 
specified in the fldnam argument and allows you to enter data in all modifia- 
ble, nonscrolled fields. 


FDV$GETDL (value.wt.dx1,fldtrm.wLr[,line.rLr[,prompt.rt.dx1]]) 


value contents of data line returned from Form Driver 
fidtrm field terminator 
line line number on which the operator’s input is displayed 


prompt data line text to serve as a prompt for the operator 
Gets a data line from a specified line on the screen. 
FDV$GETSC (fldnam.rt.dx1,fidval.wt.dx1[,fidtrm.wlL.r]) 


fidnam field name that identifies a scrolled area 
fidval field values 
fidtrm field terminator 


Positions the cursor within the current line in the scrolled area that contains 
the specified field and accepts input in modifiable fields within the line. 


FDV$ILTRM (trmmod.rLr) 
trmmod _ value for illegal terminator mode switch | 


Specifies the action to take when an illegal field terminator is entered. An ille- 
gal field terminator can be rejected by the Form Driver or ronlnned to the pro- 


gram. 
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LCHAN 


LCLOS 


LEDOF 


LEDON 


LOAD 


LOPEN 


NDISP 


PFT 


PUT 


PUTAL 


FDV$LCHAN (channel.rLr) 
channel I/O channel number for form library 


Sets the channel for form library files associated with the current terminal. 
The Form Driver uses the specified channel for any LOPEN or LCLOS call 
processing. 


FDV$LCLOS 


Closes the form library associated with the current library channel for the cur- 
rent terminal. 


FDV$LEDOF (ledno.rl.r) 

ledno terminal LED number 

Turns off the light-emitting diode (LED) on the VT100 keyboard. 
FDV$LEDON (ledno.rLr) | 

ledno terminal LED number 

Turns on the light-emitting diode (LED) on the VT100 keyboard. 
FDV$LOAD (frmnam.rt.dx1) 

frmnam form name 


Loads a form description into a workspace without displaying the form on the 
screen. 


FDV$LOPEN (filspe.rt.dx1[,channel.rl.r]) 


filspe form library file specification 
channel = [/O channel number for form library 


Opens a form library and replaces the current library channel specification if 
the I/O channel number is supplied. 


FDV$NDISP 
Marks current workspace as not displayed. 


FDV$PFT ((fidtrm.rl.r[,fldnam.rt.dx1[,fldval.rt.dx1 
[,nfidnam.wt.dx1[,nfididx.wl.r]]]]) 


fidtrm field terminator to be processed 
fidnam field name that identifies a scrolled area 
fidval field values to be displayed 


nfldnam current field name after call has been completed 
nfldidx current field index after call has been completed 


Processes the field terminator and checks for valid terminator codes. 
FDV$PUT (fidval.rt.dx1,fidnam.rt.dx1[,fididx.rLr]) 


fidval field value to be displayed 
fidnam field name 
fididx field index 


Stores the value of the fldval argument and displays that value in the speci- 
fied field. 


FDV$PUTAL ([frmval.rt.dx1)) 
frmval list of field values to be displayed 


Outputs values to all fields, stores the frmval argument values in the work- 
space for nonscrolled fields, and displays these values on the screen. 
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A-8 


PUTD 


PUTDA 


PUTL 


PUTSC 


READ 


RET 


RETAL 


RETCX 


FDV$PUTD (fidnam.rt.dx1[,fididx.rl.r]) 


fidnam field name 
fididx field index - 


Outputs the default value to a specified field. 
FDV$PUTDA 


Outputs default values to all fields in the form and displays those values on 
the screen. 


FDV$PUTL (text.rt.dx1[,line.rl.r]) 


text data line text 
line line number for displayed data line 


Outputs data to the specified line on the screen. If the line number is zero, the 
data line is displayed on the last line of the screen. 


FDV$PUTSC (fidnam.rt.dx1[,fldval.rt.dx1)) 


fidnam field name that identifies a scrolled area 
fidval field value 


Outputs data to the current line ofa scrolled area that contains the specified 
field name. 


FDV$READ (frmnam.rt.dx1,mloc.ml.da,mlocsiz.rl.r,frmsiz.w1.r) 
or 
FDV$READ (frmnam.rt.dx1,mloc.rt.dx1,mlocsiz.rl.r,frmsiz.wl.r) 


frmnam form name 


mloc form storage area 
mlocsiz _ size of memory buffer that begins with mloc 
frmsiz form size actually used 


Extracts a form from the current form library, stores it in a specified memory 
area, and adds the name of the form to the list of memory-resident forms. 


FDVS$RET (fidval.wt.dx1,fldnam.rt.dx1[,fididx.rl.r]) 


fidval field value 
fidnam field name 
fididx field index 


Returns the value for a specified field stored in the workspace. 
FDV$RETAL (frmval.wt.dx1) 
frmval concatenated values of all fields except those in scrolled areas 


Returns the values for all fields except those in scrolled areas stored in the 
workspace. . 


FDV$RETCX (atca.wa.r,awksp.wa.r,frmnam.wt.dx1,uarval.wt.dx1, 
curpos.wl.r,fidtrm.wl.r,insovr.wl.r,hlpnum.w1.r) 


-atca terminal control area address 


awksp form workspace address 
frmnam form name 
uarval value of the associated text for this VAR 


curpos cursor position within field 
fidtrm returned field terminator 
insovr Insert/Overstrike mode of field 


hipnum number of times HELP key pressed for current field 


Returns the current context of the Form Driver. You can issue this call in a 
UAR to determine the context in which the UAR is called. 
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RETDI 


RETDN 


RETFL 


RETFN 


RETFO 


RETLE 


RFRSH 


FDV$RETDI (nmdidx.rl.r,nmdval.wt.dx1[,nmdnam.wt.dx1]) 


nmdidx index of Named Data item 
nmdval text of Named Data item 
nmdnam name of Named Data item 


Returns the Named Data text that you specify by its index (rather than by its 
name). 


FDV$RETDN (nmdnanm.rt.dx1,nmdval.wt.dx1[,nmdidx.rl.r]) 


nmdnam name of Named Data item 
nmdval text of Named Data item 
nmdidx index of Named Data item 


Returns the Named Data text that you specify by its name (rather than by its 
index). 


FDV$RETFL (line.rl.r, value. wt.dx1,linlen.wlL.r[,type.rl.r]) 


line line number of form to be returned 

value value of requested line 

linlen length of character string returned in value parameter 
type type of output line requested 


Returns the contents of the line that you specify with the line argument. This 
is one of the lines displayed by the RFRSH call. This call can also be used for 
loaded but undisplayed forms for report formatting. 


FDV$RETEN (fidnam.wt.dx1[,fididx.wl.r]) 


fidnam field name 
fididx field index 


Returns the current field name and index from the current workspace. If the 
field is not indexed, the index value returned is zero. 


FDV$RETFO 


fidnum field number 
fidnam field name corresponding to fldnum 
fididx field index corresponding to fidnum 


Returns the name and index of the nth field in the form. 


FDV$RETLE (fidlen.wl.r,fidnam.rt.dx1[,fididx.rlLr)) 


fidlen field length excluding field-marker characters 
fidnam field name 
fididx field index 


Returns the number of data characters in the specified field. 
FDV$RFRSH 


Refreshes the screen. The RFRSH operation is identical to that initiated by 
pressing the CTRL/R keys. 


SCR_WIDTH FDV$SCR_WIDTH (width.Ir.r) 


SIGOP 


width 80/132 column screen width 

Tells the Form Driver the current screen width. 
FDV$SIGOP . 
Causes the application program to signal the operator. 
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SPADA’ 


SPOFF 


SPON 


SSIGQ 


SSRV 


STAT 


STERM 


STIME 


SWKSP 


TCHAN 


FDV$SPADA (mode.rl.r) 
mode numeric/application keypad mode 


Sets the alternate keypad mode. Selecting 0 sets the alternate keypad to 
numeric mode; selecting 1 sets the keypad to application mode. 


FDV$SPOFF 


Turns supervisor-only mode off for the current terminal, allowing the operator 
to modify fields protected with the Supervisor Only attribute. 


FDV$SPON 


Turns supervisor-only mode on for the current terminal, treating fields pro- 
tected with the Supervisor Only attribute as display-only fields. 


FDV$SSIGQ (sigmd.rl.r) 
sigmd bell/reverse video signaling mode 


Sets signal mode for the current terminal. Audio mode (0) rings the terminal 
bell. Video mode (1) reverses the VT100/VT200 video image. 


FDV$SSRV ([status.wl.rl,iostat.wl.r]]) 


status general status reporting variable 
iostat I/O status reporting variable 


Sets the addresses of the status reporting variables. 
FDVS$§STAT (status.wLr[,iostat.wl1.r]) 


status general status code 
iostat I/O status code 


Returns the status code for the last Form Driver call. 
FDV$STERM (tca.ml.da) 

FDV$STERM (tea.rt.dx1) 

tea terminal control area 


Sets current terminal and the workspace most recently associated with that 
terminal to the current workspace. The TCA must have been previously 
attached by the FDV$ATERM call. 


FDV$STIME (time.rl.r) 
time timeout period in seconds 


Specifies the number of seconds the Form Driver waits for operator response to 
a GET-type call. 


FDV$SWKSP (wksp.ml.da) 
or 

FDV$SWKSP (wksp.rt.dx1) 

wksp form workspace 


Specifies the workspace that the Form Driver uses for the current workspace. 
The workspace must have been previously attached by the FDV$ATERM call. 


FDV$TCHAN (channel.rl.r) 
channel ___ physical I/O channel number for terminal 


Changes the terminal channel associated with the current TCA to the speci- 
fied value. 
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USER_REFRESH FDV$USER_REFRESH((rfr_address.ra.r]) 


rfr_ user-supplied refresh routine 
address 


Sets up a user-supplied refresh screen routine. 
WAIT FDV$WAIT ((fidtrm.wl.r]) 
fidtrm field terminator code 


Causes the application program to wait until the operator presses a termina- 
tor key. This call allows the Form Driver to synchronize the application pro- 
gram to the operator's pace. 
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index 


A 


ADLVA call, 5-2, 5-3 
AFCX call, 5-3, 5-4 
AFVA call, 5-4 
Alternate keyboard mode, VT100, 
2-24 
Alternate keypad mode, 2-37, 5-69 
Area to Clear attribute, 2-4 
Asterisk (*), 5-26, 5-6 
ATERM call, 2-3, 2-4, 2-6, 5-6 
5-78 
Attaching terminals, 2-4, 5-6 
Attaching workspaces, 5-9 
Attributes 
Area to Clear, 2-4 
Autotab, 2-9 
Clear Character, 2-10, 2-11 
Date, 2-12 
default, 5-50 
Display Only, 2-11 
fill-character, 2-8, 2-9 
fixed-decimal, 2-11, 2-24 
Left Justified, 2-8, 2-24 
Must Fill, 2-10, 5-26 to 5-30, 
5-34 © 
No Echo, 2-11 
Response Required, 2-10, 5-26 
to 5-30, 5-34 
Right Justified, 2-8, 2-24 
Screen Area to Clear, 5-19 


Supervisor Only, 2-12 
Time, 2-12 
default, 5-50 
video, 2-9, 5-18, 5-23, 5-48, 
5-61, 5-72 
altering, 5-2, 5-4 
clearing, 5-18, A-5 
Zero Fill, 2-10 


Autotab attribute, 2-9, 5-9 
AWKSP call, 2-3, 2-6, 5-1 


5-9 


BELL call, 5-10 


Cc 


Call format, 5-1 
Calls 5-2 


ADLVA, 5-2, 5-3 
AFCX, 5-3, 5-4 
AFVA, 5-4, 5-6 
ATERM, 2-3, 2-5, 2-6, 5-6, 
—§-9, 5-78 
AWKSBP, 2-3, 2-6, 5-1 
5-9 
BELL, 5-1, 5-10 
CANCL, 5-11 
and UARs, 2-138, 5-12 
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CDISP, 2-3, 2-6, 5-12, 5-21 
5-11 
CLEAR, 5-113, 5-14 
CLEAR_VA, 4-3, 5-14, A-5 
Control, 1-4, 5-15 
DEL, 5-15, 5-16 
DFKBD, 2-39, 2-46, 5-16 
5-18 
DISP, 2-3, 2-6, 5-18 
DISPW, 2-3, 2-6, 5-21, 5-22, 
5-25, 5-43 
DPCOM, 2-25, 5-22, 5-23 
DTERM, 2-5, 2-6, 5-23, 5-24 
DWKSP, 2-6, 5-24 
field-level, 1-5 
form-level, 1-5, 5-25 
FIX__SCREEN, 2-4, 4-3, 5-25, 
5-26, A-7 
GET, 2-8, 2-18, 5-26 
using series of, 2-30 to 2-31 
5-28 
GETAF, 2-8, 5-28, 5-30 
GETAL, 2-8, 5-30 
and UARs, 2-13 
using, 2-30 to 2-31, 5-32 
GETDL, 2-4, 5-2, 5-19, 5-32 
5-34 
GETSC, 2-8, 5-34 
GET-type, 2-4, 2-19, 2-32, 5-43 
timeout value for, 5-76 
using, 2-30 to 2-31, 5-36 
ILTRM, 2-18, 2-37, 5-36, 5-37 
LCHAN, 2-8, 5-37, 5-38 
LCLOS, 5-37, 5-38, 5-39 
LEDOF, 5-39, 5-40 
LEDON, 5-40, 5-41 
LOAD, 2-38, 2-6, 5-21, 5-41 
5-42 
LOPEN, 2-3, 5-37, 5-42 
5-43 
NDISP, 2-6, 5-21, 5-48 
PFT, 2-32, 2-34 to 2-37, 5-26, 
5-34, 5-44 
and UARs, 2-13, 5-44 
PUT, 2-18, 5-447 
PUTAL, 2-8, 5-48 
PUT, 5-48, 5-49 - 
PUTD, 5-49 
and Date and Time attributes, 
2-12, 5-30 
PUTDA, 5-30 
and Date and Time attributes, 
2-12 
PUTL, 2-4, 2-18, 2-51, 5-2, 
5-19, 5-51, 5-53 
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PUTSC, 2-8, 5-53 
PUT-type, 2-4, 5-54 
READ, 2-3, 5-15, 5-54, 5-55 
RET, 5-55, 5-56 
RETAL, 2-8, 5-56, 5-58 
RETCX, 2-7, 2-18, 5-58 
and UARs, 2-12, 5-59 
RETDI, 5-59, 5-60 
RETDN, 5-60, 5-61 
RETFL, 5-61, 5-63 
RETFN, 5-63, 5-64 
RETFO, 5-64, 5-65 
RETLE, 5-65 
RFRSH, 2-4, 2-6, 2-18, 5-19, 
5-41, 5-61, 5-66. See also 
Refresh operation and Date and 
Time attributes, 2-12, 5-67 
SCR_WIDTH, 4-3, 5-14, 5-67, 
5-68, A-13 
SIGOP, 5-68, 5-69 
SPADA, 2-24, 2-37, 5-69 
5-70 
SPOFF, 2-12, 5-70, 5-71 
SPON, 2-12, 5-71, 5-72 
SSIGQ, 2-22, 5-72, 5-73 
SSRV, 2-46, 5-37, 5-74 
STAT, 2-46, 5-74, 5-75 
STERM, 2-5, 2-6, 5-75 
5-76 
STIME, 5-76, 5-77 
SWKSP, 2-6, 5-77, 5-78 
TCHAN, 5-6, 5-23, 5-78 
5-79 
USER_REFRESH, 5-79 
utility, 1-6, 5-81 
WAIT, 2-18, 2-20, 5-81 
Call status, checking, 2-46 
5-11 
CANCL call, 5-11 
and UARs, 2-13, 5-12 
CDISP call, 2-8, 2-6, 5-12, 5-21 
Channel, current logical library, 
specifying, 5-37 
Channel, library, 1-9 
Channel, terminal, physical, 5-78 
Channel number, I/O, 5-42 
Channel number, logical, specifying, 
5-6 
Character, deleting a, 2-26 
Characters, field-marker, 2-9 
Checking operator responses, 2-23 
5-13 
CLEAR call, 5-13 
Clear Character attribute, 2-10, 
Clearing screen, 5-13, 5-14 


CLEAR_VA, 4-3, 5-14, A-5 
Codes 
error, RMS, 2-48 
I/O status, 1-9 
key, 2-39 to 2-45 
status, 1-9, 2-48 
and UARs, 2-13 
Codes. See Status codes 
Control keys, 2-39 to 2-40 
Current field, 5-45 
name returned, 5-63 
Current logical library channel, 
specifying, 5-37 
Current scrolled line, 5-45 
Current states 
field, 1-8 
last status code, 1-9 
last terminator, 1-9 
library channel, 1-9 
scrolled line, 1-9 
supervisor-only flag, 1-9 
terminal, 1-8 
timeout value, 2-10 
workspace, 1-8 
Current terminal, 2-5 
setting, 2-5 
specifing, 5-75 
‘Current workspace, 2-5 
specifying, 5-77 
Cursor 
keys to move, 2-27 
moving to another field, 2-33 
Cursor control keys, 2-39 
Cursor position, 2-11, 5-57 
initial, 2-23 
specifying default, 5-3 


Data line, 5-32, 5-48 
Date attribute, 2-12 
default, 5-50 
Debug mode, 1-7, 2-22, 2-47, 
2-49 to 2-50, 
Decimal point, 2-11 
comma used as, 5-22 
in fixed-decimal field, 2-23 
in signed-numeric field, 2-25 
Default field-editing keys, 2-23 
Default field input mode, altering, 
5-3 
Default field values, 2-10 
Default keys, 2-24 


Default values output, 5-50, 5-50 
Defining keys, 2-46, 5-15, 5-16 
DEL call, 5-15 
Deleting a character, 2-24 
Deleting a field, 2-24 
Detaching TCAs, 5-23 
Detaching terminals, 2-5, 5-23 
Detaching workspaces, 5-16, 5-24, 5-25 
DFKBD call, 2-39, 2-46, 5-16 
Disk-resident forms, 2-1 

and Help function, 2-7, 5-18 
DISP call, 2-3, 2-6, 5-18 
Displaying forms, 2-2, 5-18 to 5-20, 

5-23 
Display Only attribute, 2-11 
Display-only fields, 5-18, 5-26 

to 5-30, 5-35, 5-55 
DISPW call, 2-3, 2-6, 5-18, 

5-21, 5-22, 5-25, 5-43 
DPCOM call, 2-22, 5-5, 5-23 
DTERM call, 2-5, 2-6, 5-23 

5-24 
DWKSP call, 2-6, 5-24 


Enter Form key, 2-11 

Enter Form terminator, 2-33 

ENTER key, 2-18, 2-22 

Error codes. See Status codes 

Errors, program, signaling 

. operator 2-51 

Exiting Scrolled Area Backward 
terminator, 2-36 

Exiting Scrolled Area Forward 
terminator, 2-36 


Field, current, 1-8, 5-44 

Field attributes. See Attributes 

Field completion UARs, 2-12, 5-28 
to 5-32, 5-34 

Field-editing functions, 2-23 

Field-editing keys, 2-22 

Field input mode, the default 
5-3 

Field length returned, 5-65 

Field-marker characters, 2-9 

Field names returned, 5-64, 5-64 

Field pictures, 2-9 
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Fields, 1-3 
default values, 2-10 
deleting, 2-24 
display only, 5-28 to 5-32, 
5-34, 5-55 
fixed-decimal, 2-23 
highlighting, 5-4 
left-justified, 2-9, 2-10 
processing, 2-9 
processing order, 2-9 
right-justified, 2-9, 2-10 
signed numeric, 2-25 
supervisor-only, 5-28 to 5-30, 
Field terminator, last, 5-57 
Field terminators, 2-28, 5-26 
processing, 5-44 
Field value 
read, 5-47, 5-49 
written, 5-30, 5-51 
Field values, 5-26 to 5-30 
written, 5-30 
Fill Character attribute, 2-10 
Fixed Decimal attribute, 2-11 
Fixed Decimal field attribute, 
2-11, 2-23, 5-25 
FIX__SCREEN, 2-4, 4-3, 5-25, 
A-7 
FMS utilities, 2-2 
Form Application Aids, 2-2 
Format, call, 5-1 
Form complete terminator, 2-33 
Form descriptions, 2-2, 2-4 
Form Driver calls. See Calls 
Form Editor, 2-2, 2-10 
and UARs, 2-13 
Form Language Translator, 2-2, 
2-10 
and UARs, 2-13 
Form library, 1-7, 2-2, 5-50 
closing, 5-38 
opening, 5-42 
Form line returned, 5-61 
Form position offset, 5-21, 5-18, 
Forms, 1-2. See also Workspaces 
and Form descriptions 
accessing, 2-1 
context of, 5-58 
disk-resident, 2-1 
and Help function, 2-7 
displaying, 2-2, 5-18 to 5-20, 
5-21 
loading, 2-3 
loading without display, 5-41 
marked as displayed, 5-49, 5-66 
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marked as undisplayed, 5-21, 
5-38, 5-41 
memory-resident, 1-7, 2-2, 5-50 
deleting, 5-15 
linking, 4-2 
‘overlaid, 2-4, 5-19 
storing, 2-1, 2-5 
Forms, memory-resident, 
deleting, 5-15 
Form values, 5-48, 5-56 
Form workspaces. See Workspaces 
Function key UARs, 2-18, 5-26, 
5-36 


G 


GET call, 2-8, 2-18, 5-26 
using, series of, 2-30 to 2-31 
5-28 
GETAF call, 5-28, 5-30 
GETAL call, 2-8, 5-30 
and UARs, 2-13 
using, 2-30 to 2-31, 
5-32 . 
GETDL call, 2-3, 5-19, 5-32 to 5-33, 
5-34 


-GETSC call, 2-8, 5-34 


GET-type calls (GET, GETAF, 
GETAL, and GETSC), 2-4, 2-19, 
2-32, 5-43 
timeout value for, 5-76 
using, 2-30 
Gold sequences, 2-40 to 2-45 


H 


Help, 5-32 
function, 2-7 
key, 2-18 
processing, 2-16 
statistics, 5-54 

Help UARs, 2-15 


I/O channel number, 5-42 

I/O status codes, 1-9 

Illegal terminators, 2-18, 2-37, 
5-36 

ILTRM call, 2-18, 2-37, 5-36 


Insert mode, 2-9, 5-3, 5-57 
keys, 2-27 
setting, 2-27 


K 


Keyboard mode, VT100 alternate, 
2-23 
Key codes, 2-39 to 2-45 
Key functions, 1-8, 2-38 
Keypad keys, 2-39 ; 
Keypad mode, alternate, 2-37, 
5-69 
Keys 
control, 2-39 to 2-40 
cursor control, 2-33 to 2-37 
default, 2-24 
default field-editing, 2-22 
defining, 2-39 to 2-45, 5-16 
field-editing, 2-22 
Insert mode, 2-27 
keypad, 2-37 
Overstrike mode, 2-27 
reserved, 2-45 to 2-46 
terminator, 2-37, 5-37 


L 


LCHAN call, 2-3, 5-37 
5-38 
LCLOS call, 5-37, 5-38 
5-39 
LEDOF call, 5-39, 5-40 
LEDON call, 5-40 
LEDs, terminal, 5-7, 5-39, 5-40 
Left-justified field, 2-8, 2-10 
Left Justified field attribute, 
2-8, 2-23 
Library, form, 1-7, 2-2, 2-8, 
5-50 
opening, 5-42 
Library channel, 1-9 
Library channel, current logical, 
specifying, 5-37 
Linking 
with a UAR vector, 4-2 
with memory-resident forms, 4-2 
with the Form Driver - 
library, 4-2, 5-41 
LOAD call, 2-3, 2-6, 5-21, 5-41 
Loading forms, 2-3 
without display, 5-41 


Loading workspaces, 2-3, 2-5 

Logical channel number 
specifying, 5-6 

Logical library channel, current, 
specifying, 5-37, 5-42 

LOPEN call, 2-3, 5-37, 5-42 


Memory-resident forms, 1-7, 2-2, 
5-50 . 
deleting, 5-15 
linking, 4-2 
Multiple workspaces, 2-6 
Must Fill attribute, 2-10, 5-26 
to 5-30, 5-30 


Named Data, 1-8 
returned by index, 5-59 
returned by name, 5-43, 5-60 
NDISP call, 2-6, 5-21, 5-43 
Next Field key, 2-10, 2-11 
Next Field terminator, 2-32 
No Echo attribute, 2-11 


e) 


Offset, form position, 5-18, 5-21 


| Operator, signaling the, 2-22, 


5-8, 5-68, 5-72 
Operator responses, checking, 
2-23 
Overlaid forms, 2-4, 5-19 
Overstrike mode, 2-9, 5-57 
keys, 2-27 
setting, 2-27 
specifying default, 5-3 


p 


PFT call, 2-32, 2-35 to 2-36, 
5-26, 5-30, 5-44 
and UARs, 2-13 
Picture, signed numeric, 2-22, 
5-25 
Pictures, field, 2-9 
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Point, decimal 
comma used as, 5-22 
Previous Field terminator, 2-37 
Program errors, signaling 
operator, 2-51, 5-47 
PUT call, 2-18, 5-47, 5-48 
PUTAL call, 2-8, 5-48, 5-49 
PUTD call, 5-49 
and Date and Time attributes, 
2-12, 5-50 
PUTDA call, 5-50 
and Date and Time attributes, 
2-12, 5-53 
PUTSC call, 2-8, 5-51, 5-53 
PUTL call, 2-4, 2-18, 5-51 to 
@ 5-52 
PUT-type calls (PUT, PUTAL, PUTD, 
and PUTDA, PUTSC), 2-4, 5-54 


R 


READ call, 2-3, 5-15, 5-54 

Refresh operation, 2-6, 2-28, 
5-13, 5-43. See also 
RFRSH call : 

Response Required attribute, 2-10, 

5-22 to 5-26, 5-30, 5-55 

RET call, 5-55, 5-56 

RETAL call, 2-8, 5-56, 5-57 

RETCX call, 2-7, 2-18, 5-57 

and UARs, 2-12, 5-59 

RETDI call, 5-59, 5-60 

RETDN call, 5-60, 5-61 

RETFL call, 5-61, 5-63 

RETFN call, 5-63, 5-64 

RETFO call, 5-64, 5-65 

RETLE call, 5-65 

Return form context, 5-57 

RETURN key, 2-18 

RFRSH call, 2-4, 2-6, 2-18, 5-19, 
5-40, 5-66. See also 
Refresh operation and Date 
and Time attributes, 2-12 

Right-justified field, 2-9, 2-10 

Right Justified field attribute, 
2-8, 2-23 

RMS system error codes, 2-48 


S 


Screen, clearing, 5-13 
Screen Area to Clear attribute, 
5-19, 5-67 


Index-6 


SCR_WIDTH, 4-3, 5-14, 5-67, 
A-13 


Screen width attribute, 5-14 
Scroll Backward terminator, 2-35 
Scrolled areas, 2-12, 5-23, 5-26 
Scrolled line, current, 1-9 
Scroll Forward terminator, 2~35 
Scrolling, 1-7, 2-12, 3-1 
Signaling the operator, 2-22, 5-8 
5-68, 5-68 
signal mode, specifying, 5-72 
signed numeric picture, 2-22 
5-25, 5-68 
SIGOP call, 5-68 
Single-character fields, 3-4 
5-69 
SPADA call, 2-23, 2-37, 5-69 
5-70 
SPOFF call, 2-12, 5-70 
5-71 
SPON call, 2-12, 5-71 
5-72 
SSIGQ call, 2-22, 5-72, 5-73 
SSRV call, 2-46, 5-73, 5-74 
STAT call, 2-46, 5-74 
States, current 
last I/O status code, 1-9 
last status code, 1-9 
last terminator, 1-9 
library channel, 1-9 
scrolled line, 1-9 
supervisor-only flag, 1-9 
terminal, 1-8 
workspace, 1-8 


Status returned from last call, 
5-74 
Status, checking call, 2-46, 3-18 
Status codes, 1-9 
and UARs, 2-13 
FMS, 2-48 
VMS, 2-48 
Status reporting variables, 
specifying, 5-73, 5-75 
STERM call, 2-5, 5-75, 5-76 
STIME call, 5-76 
Supervisor Only attribute, 2-12 
Supervisor-only fields, 5-22 to 
5-26, 5-30 
Supervisor-only flag, 1-9 
Supervisor Only mode 
off, 5-71 
on, 5-70, 5-77 
SWKSP call, 2-6, 5-77 


T 


TCAs, 1-2, 1-3, 5-40, 5-77 
See also Terminals 
detaching, 5-23 
specifying, 5-6 to 5-7 

5-78 

TCHAN call, 5-6, 5-23, 5-78 

Terminal, current, 1-8, 2-5 
setting, 2-6 
specify, 5-75 

Terminal channel, physical, 5-78 

Terminal characteristics, 4-1 

Terminal control, 2-5 

Terminal control areas. 

See TCAs 

Terminal LEDs, 5-6, 5-39 

Terminal output, direct, 4-3 

Terminals, 1-2. See also TCAs 
attaching, 5-6 
detaching, 2-5, 5-23 
key functions, 1-8 

Terminator, last, 5-57 

Terminator keys, 2-37 

Terminators, 1-9, 5-26 
Enter Form, 2-33 
Exit Scrolled Area Backward, 

2-36 
Exit Scrolled Area Forward, 
2-36 
field, 2-26 | 
for GET-type calls, 2-30 
form complete, 2-33 
illegal, 2-18, 2-36, 5-32 
Next Field, 2-10, 2-11, 2-33 
Previous Field, 2-33 
processing, 5-44 
Scroll Backward, 2-35 
Scroll Forward, 2-35 

Time attribute, 2-12 
default, 5-49 

Timeout, 2-14 

Timeout value, specifying 

for GET-type call, 5-76 


U 


UARs, 1-7, 2-12 to 2-19, 5-11, 
5-30, 5-43 
and RETCX call, 5-57 to 5-58 
field completion, 2-13, 5-26 to 
5-30 
function key, 2-18, 5-22, 5-32 


help, 2-15 
legal actions in, 2-19 
post-help, 2-16 
pre-help, 2-15 
UAR vector, linking with, 4-2 
User action routines. See UARs 
5-79 
USER__REFRESH 5-79 
Utilities, FMS, 2-2 


Vv 


Video attributes, 2-9, 5-14, 5-23 
5-51, 5-61, 5-72 
altering, 5-2, 5-4 
VT100 alternate keyboard mode, 
2-23, 5-81 


W 


WAIT call, 2-18, 2-20, 5-81 
Workspace, current, 1-8, 2-6 
specifying, 5-77 
Workspaces, 1-2, 1-3. See 
also Forms and Form 
descriptions 
attaching, 5-7 
detaching, 5-23 
loading, 2-3, 2-6 
multiple, 2-6 
Workspace size, estimating, 5-9 


Z 


Zero Fill attribute, 2-10, 2-11 
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VAX FMS 

Form Driver 
Reference Manual 
AA-L319B-TE 


READER’S COMMENTS 
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 


company’s discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well organized? Please make suggestions for improvement. 





























Did you find errors in this manual? If so, specify the error and the page number. 








Please indicate the type of user/reader that you most nearly represent. 





[] Assembly language programmer 
() Higher-level language programmer 
[) Occasional programmer (experienced) 
(] User with little programming experience 
L] Student programmer 
C] Other (please specify) 
Name — ee Dat 
Organization 
Street 
City State. Zip Code 





or Country 
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